ddi_mem_alloc.9f revision c10c16dec587a0662068f6e2991c29ed3a9db943
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]
ddi_mem_alloc 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers"
NAME
ddi_mem_alloc, ddi_mem_free - allocate and free sequentially accessed memory
SYNOPSIS

#include <sys/ddi.h> 
#include <sys/sunddi.h>

int ddi_mem_alloc(dev_info_t *dip, ddi_dma_lim_t *limits, 
 uint_t length, uint_t flags, caddr_t *kaddrp, 
 uint_t *real_length);


void ddi_mem_free(caddr_t kaddr);
INTERFACE LEVEL

These interfaces are obsolete. ddi_dma_mem_alloc(9F) and ddi_dma_mem_free(9F) should be used instead.

PARAMETERS
"ddi_mem_alloc()"

dip

A pointer to the device's dev_info structure.

limits

A pointer to a DMA limits structure for this device (see ddi_dma_lim_sparc(9S) or ddi_dma_lim_x86(9S)). If this pointer is NULL, a default set of DMA limits is assumed.

length

The length in bytes of the desired allocation.

flags

The possible flags 1 and 0 are taken to mean, respectively, wait until memory is available, or do not wait.

kaddrp

On a successful return, *kaddrp points to the allocated memory.

real_length

The length in bytes that was allocated. Alignment and padding requirements may cause ddi_mem_alloc() to allocate more memory than requested in length.

"ddi_mem_free()"

kaddr

The memory returned from a successful call to ddi_mem_alloc().

DESCRIPTION

The ddi_mem_alloc() function allocates memory for DMA 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 streaming access. The allocation will obey the alignment and padding constraints as specified by the limits argument and other limits imposed by the system.

Note that you must still use DMA resource allocation functions (see ddi_dma_setup(9F)) to establish DMA resources for the memory allocated using ddi_mem_alloc(). ddi_mem_alloc() 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. ddi_dma_setup(9F) requires the actual length.

In order to make the view of a memory object shared between a CPU and a DMA device consistent, explicit synchronization steps using ddi_dma_sync(9F) or ddi_dma_free(9F) are required.

The ddi_mem_free() function frees up memory allocated by ddi_mem_alloc().

RETURN VALUES

The ddi_mem_alloc() function returns:

DDI_SUCCESS

Memory successfully allocated.

DDI_FAILURE

Allocation failed.

CONTEXT

The ddi_mem_alloc() function can be called from user, interrupt, or kernel context, except when flags is set to 1, in which case it cannot be called from interrupt context.

ATTRIBUTES

See attributes(5) for a description of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
Stability LevelObsolete
SEE ALSO

attributes(5), ddi_dma_free(9F), ddi_dma_mem_alloc(9F), ddi_dma_mem_free(9F), ddi_dma_setup(9F), ddi_dma_sync(9F), ddi_iopb_alloc(9F), ddi_dma_lim_sparc(9S), ddi_dma_lim_x86(9S), ddi_dma_req(9S)

Writing Device Drivers