'\" te
.\"  Copyright (c) 2006 Sun Microsystems, Inc.  All Rights Reserved.
.TH ddi_mem_alloc 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.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
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 15n
.rt  
A pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlimits\fR\fR
.ad
.RS 15n
.rt  
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
.mk
.na
\fB\fIlength\fR\fR
.ad
.RS 15n
.rt  
The length in bytes of the desired allocation.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 15n
.rt  
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
.mk
.na
\fB\fIkaddrp\fR\fR
.ad
.RS 15n
.rt  
On a successful return, *\fIkaddrp\fR points to the allocated memory.
.RE

.sp
.ne 2
.mk
.na
\fB\fIreal_length\fR\fR
.ad
.RS 15n
.rt  
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
.mk
.na
\fB\fIkaddr\fR\fR
.ad
.RS 9n
.rt  
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
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
.rt  
Memory successfully allocated.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
.rt  
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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityObsolete
.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 for Oracle Solaris 11.2\fR