'\" te
.\"  Copyright (c) 2007, 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_umem_lock 9F "10 Apr 2007" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_umem_lock, ddi_umem_unlock \- lock and unlock memory pages
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h> 
#include <sys/sunddi.h>

\fBint\fR \fBddi_umem_lock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR, 
     \fBddi_umem_cookie_t\fR *\fIcookiep\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_umem_unlock\fR(\fBddi_umem_cookie_t\fR \fIcookie\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.SS "ddi_umem_lock"
.sp
.ne 2
.mk
.na
\fB\fIaddr\fR\fR
.ad
.RS 11n
.rt  
Virtual address of memory object
.RE

.sp
.ne 2
.mk
.na
\fB\fIlen\fR\fR
.ad
.RS 11n
.rt  
Length of memory object in bytes
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 11n
.rt  
Valid flags include:
.sp
.ne 2
.mk
.na
\fBDDI_UMEMLOCK_READ\fR
.ad
.RS 21n
.rt  
Memory pages are locked to be read from. (Disk write or a network send.)
.RE

.sp
.ne 2
.mk
.na
\fBDDI_UMEMLOCK_WRITE\fR
.ad
.RS 22n
.rt  
Memory pages are locked to be written to. (Disk read or a network receive.)
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIcookiep\fR\fR
.ad
.RS 11n
.rt  
Pointer to a kernel memory cookie.
.RE

.SS "ddi_umem_unlock"
.sp
.ne 2
.mk
.na
\fBcookie\fR
.ad
.RS 10n
.rt  
Kernel memory cookie allocated by \fBddi_umem_lock()\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_umem_lock()\fR function locks down the physical pages (including I/O
pages) that correspond to the current process' virtual address range
[\fIaddr\fR, \fIaddr\fR + \fIsize\fR) and fills in a cookie representing the
locked pages. This cookie can be used to create a \fBbuf\fR(9S) structure that
can be used to perform I/O (see \fBddi_umem_iosetup\fR(9F) and
\fBddi_dma_buf_bind_handle\fR(9F), or it can be used with
\fBdevmap_umem_setup\fR(9F) to export the memory to an application.
.sp
.LP
The virtual address and length specified must be at a page boundary and the
mapping performed in terms of the system page size. See \fBpagesize\fR(1).
.sp
.LP
The flags argument indicates the intended use of the locked memory. Set flags
to \fBDDI_UMEMLOCK_READ\fR if the memory pages will be read (for example, in a
disk write or a network send.) Set flags to \fBDDI_UMEMLOCK_WRITE\fR if the
memory pages will be written (for example, in a disk read or a network
receive). You must choose one (and only one) of these values.
.sp
.LP
To unlock the locked pages, the drivers call \fBddi_umem_unlock(9F)\fR with the
cookie obtained from \fBddi_umem_lock()\fR.
.sp
.LP
The process is not allowed to \fBexec\fR(2) or \fBfork\fR(2) while its physical
pages are locked down by the device driver.
.sp
.LP
The device driver must ensure that the physical pages have been unlocked after
the application has called \fBclose\fR(2).
.SH RETURN VALUES
.sp
.LP
On success, a \fB0\fR is returned. Otherwise, one of the following \fBerrno\fR
values is returned.
.sp
.ne 2
.mk
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
.rt  
User process has no mapping at that address range or does not support locking
.RE

.sp
.ne 2
.mk
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
.rt  
User process does not have the required permission.
.RE

.sp
.ne 2
.mk
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
.rt  
The system does not have sufficient resources to lock memory, or locking
\fIlen\fR memory would exceed a limit or resource control on locked memory.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt  
Could not allocate system resources required to lock the pages. The
\fBddi_umem_lock()\fR could succeed at a later time.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
Requested memory is not aligned on a system page boundary.
.RE

.SH CONTEXT
.sp
.LP
The \fBddi_umem_lock()\fR function can only be called from user context;
\fBddi_umem_unlock()\fR from user, kernel, and interrupt contexts.
.SH SEE ALSO
.sp
.LP
\fBddi_umem_iosetup\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
\fBdevmap_umem_setup\fR(9F), \fBddi_umem_alloc\fR(9F)
.SH NOTES
.sp
.LP
The \fBddi_umem_unlock()\fR function consumes physical memory. The driver is
responsible for a speedy unlock to free up the resources.
.sp
.LP
The \fBddi_umem_unlock()\fR function can defer unlocking of the pages to a
later time depending on the implementation.