'\" te
.\"  Copyright (c) 2006 Sun Microsystems, Inc.  All Rights Reserved.
.\" 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_MEM_ALLOC 9F "Apr 04, 2006"
.SH NAME
ddi_mem_alloc, ddi_mem_free \- allocate and free sequentially accessed memory
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint\fR \fBddi_mem_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimits\fR,
     \fBuint_t\fR \fIlength\fR, \fBuint_t\fR \fIflags\fR, \fBcaddr_t *\fR\fIkaddrp\fR,
     \fBuint_t *\fR\fIreal_length\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_mem_free\fR(\fBcaddr_t\fR \fIkaddr\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
These interfaces are obsolete. \fBddi_dma_mem_alloc\fR(9F) and
\fBddi_dma_mem_free\fR(9F) should be used instead.
.SH PARAMETERS
.SS "\fBddi_mem_alloc()\fR"
.sp
.ne 2
.na
\fB\fIdip\fR\fR
.ad
.RS 15n
A pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fIlimits\fR\fR
.ad
.RS 15n
A pointer to a \fBDMA\fR limits 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\fR limits is assumed.
.RE

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

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 15n
The possible flags \fB1\fR and \fB0\fR are taken to mean, respectively, wait
until memory is available, or do not wait.
.RE

.sp
.ne 2
.na
\fB\fIkaddrp\fR\fR
.ad
.RS 15n
On a successful return, *\fIkaddrp\fR points to the allocated memory.
.RE

.sp
.ne 2
.na
\fB\fIreal_length\fR\fR
.ad
.RS 15n
The length in bytes that was allocated. Alignment and padding requirements may
cause \fBddi_mem_alloc()\fR to allocate more memory than requested in
\fIlength\fR.
.RE

.SS "\fBddi_mem_free()\fR"
.sp
.ne 2
.na
\fB\fIkaddr\fR\fR
.ad
.RS 9n
The memory returned from a successful call to \fBddi_mem_alloc()\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_mem_alloc()\fR function allocates memory for \fBDMA\fR transfers and
should be used if the device is performing sequential, unidirectional,
block-sized and block-aligned transfers to or from memory. This type of access
is commonly known as \fBstreaming\fR access. The allocation will obey the
alignment and padding constraints as specified by the \fIlimits\fR argument and
other limits imposed by the system.
.sp
.LP
Note that you must still use \fBDMA\fR resource allocation functions (see
\fBddi_dma_setup\fR(9F)) to establish \fBDMA\fR resources for the memory
allocated using \fBddi_mem_alloc()\fR. \fBddi_mem_alloc()\fR returns the actual
size of the allocated memory object.  Because of padding and alignment
requirements, the actual size might be larger than the requested size.
\fBddi_dma_setup\fR(9F) requires the actual length.
.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 required.
.sp
.LP
The \fBddi_mem_free()\fR function frees up memory allocated by
\fBddi_mem_alloc()\fR.
.SH RETURN VALUES
.sp
.LP
The \fBddi_mem_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
The \fBddi_mem_alloc()\fR function can be called from user, interrupt, or
kernel context, except when \fIflags\fR is set to \fB1\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
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_iopb_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