'\" te .\" Copyright (c) 2006, Sun Microsystems, Inc. .TH ddi_dma_setup 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" .SH NAME ddi_dma_setup \- setup DMA resources .SH SYNOPSIS .LP .nf #include #include \fBint\fR \fBddi_dma_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_req_t *\fR\fIdmareqp\fR, \fBddi_dma_handle_t *\fR\fIhandlep\fR); .fi .SH INTERFACE LEVEL .sp .LP This interface is obsolete. The functions \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_free_handle\fR(9F), and \fBddi_dma_unbind_handle\fR(9F) should be used instead. .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIdip\fR\fR .ad .RS 11n .rt A pointer to the device's \fBdev_info\fR structure. .RE .sp .ne 2 .mk .na \fB\fIdmareqp\fR\fR .ad .RS 11n .rt A pointer to a \fBDMA\fR request structure (see \fBddi_dma_req\fR(9S)). .RE .sp .ne 2 .mk .na \fB\fIhandlep\fR\fR .ad .RS 11n .rt A pointer to a \fBDMA\fR handle to be filled in. See below for a discussion of a handle. If \fIhandlep\fR is \fINULL\fR, the call to \fBddi_dma_setup()\fR 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. .RE .SH DESCRIPTION .sp .LP The \fBddi_dma_setup()\fR function allocates resources for a memory object such that a device can perform \fBDMA\fR to or from that object. .sp .LP A call to \fBddi_dma_setup()\fR informs the system that device referred to by \fIdip\fR wishes to perform \fBDMA\fR to or from a memory object. The memory object, the device's \fBDMA\fR capabilities, the device driver's policy on whether to wait for resources, are all specified in the \fBddi_dma_req\fR structure pointed to by \fIdmareqp\fR. .sp .LP A successful call to \fBddi_dma_setup()\fR fills in the value pointed to by \fIhandlep\fR. This is an opaque object called a \fBDMA\fR handle. This handle is then used in subsequent \fBDMA\fR calls, until \fBddi_dma_free\fR(9F) is called. .sp .LP Again a \fBDMA\fR handle is opaque\(emdrivers may \fBnot\fR attempt to interpret its value. When a driver wants to enable its \fBDMA\fR engine, it must retrieve the appropriate address to supply to its \fBDMA\fR engine using a call to \fBddi_dma_htoc\fR(9F), which takes a pointer to a \fBDMA\fR handle and returns the appropriate \fBDMA\fR address. .sp .LP When \fBDMA\fR transfer completes, the driver should free up the allocated \fBDMA\fR resources by calling \fBddi_dma_free()\fR .SH RETURN VALUES .sp .LP The \fBddi_dma_setup()\fR function returns: .sp .ne 2 .mk .na \fB\fBDDI_DMA_MAPPED\fR\fR .ad .RS 23n .rt Successfully allocated resources for the object. In the case of an \fBadvisory\fR call, this indicates that the request is legal. .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_PARTIAL_MAP\fR\fR .ad .RS 23n .rt Successfully allocated resources for a \fBpart\fR of the object. This is acceptable when partial transfers are allowed using a flag setting in the \fBddi_dma_req\fR structure (see \fBddi_dma_req\fR(9S) and \fBddi_dma_movwin\fR(9F)). .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_NORESOURCES\fR\fR .ad .RS 23n .rt When no resources are available. .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_NOMAPPING\fR\fR .ad .RS 23n .rt The object cannot be reached by the device requesting the resources. .RE .sp .ne 2 .mk .na \fB\fBDDI_DMA_TOOBIG\fR\fR .ad .RS 23n .rt The object is too big and exceeds the available resources. The maximum size varies depending on machine and configuration. .RE .SH CONTEXT .sp .LP The \fBddi_dma_setup()\fR function can be called from user, interrupt, or kernel context, except when the \fBdmar_fp\fR member of the \fBddi_dma_req\fR structure pointed to by \fIdmareqp\fR is set to \fBDDI_DMA_SLEEP\fR, in which case it cannot be called from interrupt context. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for a description of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . \fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR _ Stability LevelObsolete .TE .SH SEE ALSO .sp .LP \fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_free_handle\fR(9F), \fBddi_dma_unbind_handle\fR(9F)\fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), \fBddi_dma_free\fR(9F), \fBddi_dma_htoc\fR(9F), \fBddi_dma_movwin\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_req\fR(9S) .sp .LP \fIWriting Device Drivers for Oracle Solaris 11.2\fR .SH NOTES .sp .LP The construction of the \fBddi_dma_req\fR structure is complicated. Use of the provided interface functions such as \fBddi_dma_buf_setup\fR(9F) simplifies this task.