'\" te
.\"  Copyright (c) 1996, 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 DEVMAP_MAP 9E "Jan 7, 1997"
.SH NAME
devmap_map \- device mapping create entry point
.SH SYNOPSIS
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint prefix\fR\fBdevmap_map\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBdev_t\fR \fIdev\fR,
     \fBuint_t\fR \fIflags\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBvoid **\fR\fIpvtp\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH ARGUMENTS
.ne 2
.na
\fB\fIdhp\fR \fR
.ad
.RS 10n
An opaque mapping handle that the system uses to describe the mapping currently
being created.
.RE

.sp
.ne 2
.na
\fB\fIdev\fR \fR
.ad
.RS 10n
The device whose memory is to be mapped.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR \fR
.ad
.RS 10n
Flags indicating type of mapping. Possible values are:
.sp
.ne 2
.na
\fB\fBMAP_PRIVATE\fR \fR
.ad
.RS 16n
Changes are private.
.RE

.sp
.ne 2
.na
\fB\fBMAP_SHARED\fR \fR
.ad
.RS 16n
Changes should be shared.
.RE

.RE

.sp
.ne 2
.na
\fB\fIoff\fR \fR
.ad
.RS 10n
User offset within the logical device memory at which the mapping begins.
.RE

.sp
.ne 2
.na
\fB\fIlen\fR \fR
.ad
.RS 10n
Length (in bytes) of the memory to be mapped.
.RE

.sp
.ne 2
.na
\fB\fIpvtp\fR \fR
.ad
.RS 10n
A pointer to be filled in by device drivers with the driver private mapping
data.
.RE

.SH DESCRIPTION
The \fBdevmap_map()\fR entry point is an optional routine that allows drivers
to perform additional processing or to allocate private resources during the
mapping setup time.  For example, in order for device drivers to support
context switching, the drivers allocate private mapping data and associate the
private data with the mapping parameters in the \fBdevmap_map()\fR entry point.
.sp
.LP
The system calls \fBdevmap_map()\fR after the user mapping to device physical
memory has been established. (For example, after the  \fBdevmap\fR(9E) entry
point is called.)
.sp
.LP
\fBdevmap_map()\fR receives a pointer to the driver private data  for this
mapping in \fIpvtp\fR. The system expects the driver to allocate its private
data and set  \fI*pvtp\fR to the allocated data.  The driver must store
\fIoff\fR and \fIlen\fR, which define the range of the mapping, in its private
data.  Later, when the system calls \fBdevmap_unmap\fR(9E), the driver will use
the \fIoff\fR and  \fIlen\fR stored in \fIpvtp\fR to check if the entire
mapping, or just a part of it, is being unmapped. If only a part of the mapping
is being unmapped, the driver must allocate  a new private data for the
remaining mapping before freeing the old private data.  The driver will receive
\fI*pvtp\fR in subsequent event notification callbacks.
.sp
.LP
If the driver support context switching,  it should store the mapping handle
\fIdhp\fR in its private data \fI*pvtp\fR for later use in
\fBdevmap_unload\fR(9F).
.sp
.LP
For a driver that supports context switching, \fIflags\fR indicates whether or
not the driver should allocate a private context  for the mapping.  For
example, a driver may allocate a memory region to store the device context if
\fIflags\fR is set to  \fBMAP_PRIVATE\fR.
.SH RETURN VALUES
\fBdevmap_map()\fR returns the following values:
.sp
.ne 2
.na
\fB\fB0\fR \fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fBNon-zero\fR
.ad
.RS 12n
An error occurred.
.RE

.SH EXAMPLES
\fBExample 1 \fR \fBdevmap_map()\fRimplementation
.sp
.LP
The following shows an example implementation for \fBdevmap_map()\fR.

.sp
.in +2
.nf
static int
xxdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, \e
     offset_t off,size_t len, void **pvtp)
{
	struct xx_resources  *pvt;
	struct xx_context *this_context;
	struct xx_softc *softc;
	softc = ddi_get_soft_state(statep, getminor(dev));

	this_context = get_context(softc, off, len);

	/* allocate resources for the mapping  - Device dependent */
	pvt = kmem_zalloc(sizeof (struct xx_resources), KM_SLEEP);

	pvt->off = off;
	pvt->len = len;
	pvt->dhp = dhp;
	pvt->ctx = this_context;
	*pvtp = pvt;
}
.fi
.in -2

.SH SEE ALSO
.BR devmap_unmap (9E),
.BR devmap_unload (9F),
.BR devmap_callback_ctl (9S)
.sp
.LP
\fIWriting Device Drivers\fR