Copyright (c) 2006, Sun Microsystems, Inc.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#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.
dip
A pointer to the device's dev_info structure.
dmareqp
A pointer to a DMA request structure (see ddi_dma_req(9S)).
handlep
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\(emdrivers 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:
DDI_DMA_MAPPED
Successfully allocated resources for the object. In the case of an advisory call, this indicates that the request is legal.
DDI_DMA_PARTIAL_MAP
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)).
DDI_DMA_NORESOURCES
When no resources are available.
DDI_DMA_NOMAPPING
The object cannot be reached by the device requesting the resources.
DDI_DMA_TOOBIG
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:
| 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)
Writing Device Drivers
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.