'\" te
.\" 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]
.TH DDI_IOPB_ALLOC 9F "Apr 04, 2006"
.SH NAME
ddi_iopb_alloc, ddi_iopb_free \- allocate and free non-sequentially accessed
memory
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBddi_iopb_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimits\fR,
     \fBuint_t\fR \fIlength\fR, \fBcaddr_t *\fR\fIiopbp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_iopb_free\fR(\fBcaddr_t\fR \fIiopb\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
These interfaces are obsolete. Use \fBddi_dma_mem_alloc\fR(9F) instead of
\fBddi_iopb_alloc()\fR. Use \fBddi_dma_mem_free\fR(9F) instead of
\fBddi_iopb_free()\fR.
.SH PARAMETERS
.SS "\fBddi_iopb_alloc()\fR"
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 10n
A pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIlimits\fR\fR
.ad
.RS 10n
A pointer to a \fBDMA \fRlimits structure for this device (see
\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). If this pointer is
\fINULL\fR, a default set of \fBDMA \fRlimits is assumed.
.RE

.sp
.ne 2
.na
\fB\fIlength\fR\fR
.ad
.RS 10n
The length in bytes of the desired allocation.
.RE

.sp
.ne 2
.na
\fB\fIiopbp\fR\fR
.ad
.RS 10n
A pointer to a \fBcaddr_t\fR. On a successful return, \fI*iopbp\fR points to
the allocated storage.
.RE

.SS "\fBddi_iopb_free()\fR"
.sp
.ne 2
.na
\fB\fIiopb\fR\fR
.ad
.RS 8n
The \fIiopb\fR returned from a successful call to \fBddi_iopb_alloc()\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_iopb_alloc()\fR function allocates memory for \fBDMA\fR transfers
and should be used if the device accesses memory in a non-sequential fashion,
or if synchronization steps using \fBddi_dma_sync\fR(9F) should be as
lightweight as possible, due to frequent use on small objects. This type of
access is commonly known as \fIconsistent\fR access. The allocation will obey
the alignment and padding constraints as specified in the \fIlimits\fR argument
and other limits imposed by the system.
.sp
.LP
Note that you still must use \fBDMA\fR resource allocation functions (see
\fBddi_dma_setup\fR(9F)) to establish \fBDMA\fR resources for the memory
allocated using \fBddi_iopb_alloc()\fR.
.sp
.LP
In order to make the view of a memory object shared between a \fBCPU\fR and a
\fBDMA\fR device consistent, explicit synchronization steps using
\fBddi_dma_sync\fR(9F) or \fBddi_dma_free\fR(9F) are still required. The
\fBDMA\fR resources will be allocated so that these synchronization steps are
as efficient as possible.
.sp
.LP
The \fBddi_iopb_free()\fR function frees up memory allocated by
\fBddi_iopb_alloc()\fR.
.SH RETURN VALUES
.sp
.LP
The \fBddi_iopb_alloc()\fR function returns:
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
Memory successfully allocated.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
Allocation failed.
.RE

.SH CONTEXT
.sp
.LP
These functions can be called from user, interrupt, or kernel context.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Stability Level	Obsolete
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_dma_free\fR(9F), \fBddi_dma_mem_alloc\fR(9F),
\fBddi_dma_mem_free\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F),
\fBddi_mem_alloc\fR(9F), \fBddi_dma_lim_sparc\fR(9S),
\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
.sp
.LP
This function uses scarce system resources. Use it selectively.