ddi_dma_setup - setup DMA resources
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_dma_setup(dev_info_t *dip, ddi_dma_req_t *dmareqp,
ddi_dma_handle_t *handlep);
This interface is obsolete. The functions ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F), ddi_dma_buf_bind_handle(9F), ddi_dma_free_handle(9F), and ddi_dma_unbind_handle(9F) should be used instead.
A pointer to the device's dev_info structure.
A pointer to a DMA request structure (see ddi_dma_req(9S)).
A pointer to a DMA handle to be filled in. See below for a discussion of a handle. If handlep is NULL, the call to ddi_dma_setup() is considered an advisory call, in which case no resources are allocated, but a value indicating the legality and the feasibility of the request is returned.
The ddi_dma_setup() function allocates resources for a memory object such that a device can perform DMA to or from that object.
A call to ddi_dma_setup() informs the system that device referred to by dip wishes to perform DMA to or from a memory object. The memory object, the device's DMA capabilities, the device driver's policy on whether to wait for resources, are all specified in the ddi_dma_req structure pointed to by dmareqp.
A successful call to ddi_dma_setup() fills in the value pointed to by handlep. This is an opaque object called a DMA handle. This handle is then used in subsequent DMA calls, until ddi_dma_free(9F) is called.
Again a DMA handle is opaque—drivers may not attempt to interpret its value. When a driver wants to enable its DMA engine, it must retrieve the appropriate address to supply to its DMA engine using a call to ddi_dma_htoc(9F), which takes a pointer to a DMA handle and returns the appropriate DMA address.
When DMA transfer completes, the driver should free up the allocated DMA resources by calling ddi_dma_free()
The ddi_dma_setup() function returns:
Successfully allocated resources for the object. In the case of an advisory call, this indicates that the request is legal.
Successfully allocated resources for a part of the object. This is acceptable when partial transfers are allowed using a flag setting in the ddi_dma_req structure (see ddi_dma_req(9S) and ddi_dma_movwin(9F)).
When no resources are available.
The object cannot be reached by the device requesting the resources.
The object is too big and exceeds the available resources. The maximum size varies depending on machine and configuration.
The ddi_dma_setup() function can be called from user, interrupt, or kernel context, except when the dmar_fp member of the ddi_dma_req structure pointed to by dmareqp is set to DDI_DMA_SLEEP, in which case it cannot be called from interrupt context.
See attributes(5) for a description of the following attributes:
|
attributes(5), ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F), ddi_dma_buf_bind_handle(9F), ddi_dma_free_handle(9F), ddi_dma_unbind_handle(9F)ddi_dma_addr_setup(9F), ddi_dma_buf_setup(9F), ddi_dma_free(9F), ddi_dma_htoc(9F), ddi_dma_movwin(9F), ddi_dma_sync(9F), ddi_dma_req(9S)
Writing Device Drivers for Oracle Solaris 11.3
The construction of the ddi_dma_req structure is complicated. Use of the provided interface functions such as ddi_dma_buf_setup(9F) simplifies this task.