Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
Kernel Functions for Driversddi_umem_lock(9F)


NAME

 ddi_umem_lock, ddi_umem_unlock - lock and unlock memory pages

SYNOPSIS

 
#include <sys/ddi.h> 
#include <sys/sunddi.h>
int ddi_umem_lock(caddr_t addr, size_t len, int flags, ddi_umem_cookie_t *cookiep);
 void ddi_umem_unlock(ddi_umem_cookie_t cookie);

INTERFACE LEVEL

 

Solaris DDI specific (Solaris DDI)

PARAMETERS

 

ddi_umem_lock

 
addr
Virtual address of memory object
len
Length of memory object in bytes
flags
Valid flags include:
DDI_UMEMLOCK_READ
Memory pages are locked to be read from. (Disk write or a network send.)
DDI_UMEMLOCK_WRITE
Memory pages are locked to be written to. (Disk read or a network receive.)
cookiep
Pointer to a kernel memory cookie.

ddi_umem_unlock

 
cookie
Kernel memory cookie allocated by ddi_umem_lock().

DESCRIPTION

 

The ddi_umem_lock(9F) function locks down the physical pages (including I/O pages) that correspond to the current process' virtual address range [addr, addr + size) and fills in a cookie representing the locked pages. This cookie can be used to create a buf(9S) structure that can be used to perform I/O (see ddi_umem_iosetup(9F) and ddi_dma_buf_bind_handle(9F)), or it can be used with devmap_umem_setup(9F) to export the memory to an application.

The flags argument indicates the intended use of the locked memory. Set flags to DDI_UMEMLOCK_READ if the memory pages will be read (for example, in a disk write or a network send.) Set flags to DDI_UMEMLOCK_WRITE if the memory pages will be written (for example, in a disk read or a network receive).

To unlock the locked pages, the drivers call ddi_umem_unlock(9F) with the cookie obtained from ddi_umem_lock(9F).

The process is not allowed to exec(2) or fork(2) while its physical pages are locked down by the device driver.

The device driver must ensure that the physical pages have been unlocked after the application has called close(2).

RETURN VALUES

 

On success, a 0 is returned. Otherwise, one of the following errno values is returned.

EFAULT
User process has no mapping at that address range or does not support locking
EACCES
User process does not have the required permission.
ENOMEM
The system does not have sufficient resources to lock memory.
EAGAIN
Could not allocate system resources required to lock the pages. The ddi_umem_lock() could succeed at a later time.

CONTEXT

 

The ddi_umem_lock() function can only be called from user context; ddi_umem_unlock() from user, kernel, and interrupt contexts.

SEE ALSO

 

ddi_umem_iosetup(9F), ddi_dma_buf_bind_handle(9F), devmap_umem_setup(9F), ddi_umem_alloc(9F)

NOTES

 

The ddi_umem_lock(9F) function consumes physical memory. The driver is responsible for a speedy unlock to free up the resources.

ddi_umem_unlock() can defer unlocking of the pages to a later time depending on the implementation.


SunOS 5.9Go To TopLast Changed 25 Sep 2001

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.