NAME | SYNOPSIS | INTERFACE LEVEL | PARAMETERS | DESCRIPTION | RETURN VALUES | CONTEXT | ATTRIBUTES | SEE ALSO | NOTES
#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.
ddi_dma_setup() 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 the allocated DMA resources by calling ddi_dma_free().
ddi_dma_setup() 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.
ddi_dma_setup() can be called from user or interrupt 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 can be called from user context only.
See attributes(5) for a description of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Stability Level | Obsolete |
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)
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.
NAME | SYNOPSIS | INTERFACE LEVEL | PARAMETERS | DESCRIPTION | RETURN VALUES | CONTEXT | ATTRIBUTES | SEE ALSO | NOTES