'\" 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_CONTEXTMGT 9E "Jan 16, 1997"
.SH NAME
devmap_contextmgt \- driver callback function for context management
.SH SYNOPSIS
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBdevmap_contextmgt\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR,
     \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR);
.fi

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

.sp
.ne 2
.na
\fB\fIpvtp\fR \fR
.ad
.RS 9n
Driver private mapping data.
.RE

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

.sp
.ne 2
.na
\fB\fIlen\fR \fR
.ad
.RS 9n
Length (in bytes) of the memory being accessed.
.RE

.sp
.ne 2
.na
\fB\fItype\fR \fR
.ad
.RS 9n
Type of access operation. Possible values are:
.sp
.ne 2
.na
\fB\fBDEVMAP_ACCESS\fR \fR
.ad
.RS 18n
Memory access.
.RE

.sp
.ne 2
.na
\fB\fBDEVMAP_LOCK\fR \fR
.ad
.RS 18n
Lock the memory being accessed.
.RE

.sp
.ne 2
.na
\fB\fBDEVMAP_UNLOCK\fR \fR
.ad
.RS 18n
Unlock the memory being accessed.
.RE

.RE

.sp
.ne 2
.na
\fB\fIrw\fR \fR
.ad
.RS 9n
Direction of access. Possible values are:
.sp
.ne 2
.na
\fB\fBDEVMAP_READ\fR \fR
.ad
.RS 17n
Read access attempted.
.RE

.sp
.ne 2
.na
\fB\fBDEVMAP_WRITE\fR \fR
.ad
.RS 17n
Write access attempted.
.RE

.RE

.SH DESCRIPTION
\fBdevmap_contextmgt()\fR is a driver-supplied function that performs device
context switching on a  mapping.  Device drivers pass \fBdevmap_contextmgt()\fR
as an argument to \fBdevmap_do_ctxmgt\fR(9F) in the  \fBdevmap_access\fR(9E)
entry point. The system will call \fBdevmap_contextmgt()\fR when memory is
accessed. The system expects  \fBdevmap_contextmgt()\fR to load the memory
address translations of the mapping by calling \fBdevmap_load\fR(9F) before
returning.
.sp
.LP
\fIdhp\fR uniquely identifies the mapping and is used as an argument to
\fBdevmap_load\fR(9F) to validate the mapping. \fIoff\fR and \fIlen\fR define
the range to be affected by the operations in \fBdevmap_contextmgt()\fR.
.sp
.LP
The driver must check if there is already a mapping established at \fIoff\fR
that needs to be unloaded. If a mapping exists at \fIoff\fR,
\fBdevmap_contextmgt()\fR must call  \fBdevmap_unload\fR(9F) on the current
mapping. \fBdevmap_unload\fR(9F) must be followed by \fBdevmap_load()\fR on the
mapping that generated this call to \fBdevmap_contextmgt()\fR.
\fBdevmap_unload\fR(9F) unloads the current mapping so that a call to
\fBdevmap_access\fR(9E), which causes the system to call
\fBdevmap_contextmgt()\fR, will be generated the next time the mapping is
accessed.
.sp
.LP
\fIpvtp\fR is a pointer to the driver's private mapping data that was allocated
and initialized in the \fBdevmap_map\fR(9E) entry point. \fItype\fR defines the
type of operation that device drivers should perform on the memory object.  If
\fItype\fR is either \fBDEVMAP_LOCK\fR or \fBDEVMAP_UNLOCK\fR, the length
passed to either \fBdevmap_unload\fR(9F) or \fBdevmap_load\fR(9F) must be same
as \fIlen\fR. \fIrw\fR specifies the access direction on the memory object.
.sp
.LP
A non-zero return value from  \fBdevmap_contextmgt()\fR will be returned to
\fBdevmap_access\fR(9E) and will cause the corresponding operation to fail. The
failure may result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to
the process.
.SH RETURN VALUES
.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 \fRmanaging a device context
.sp
.LP
The following shows an example of managing a device context.

.sp
.in +2
.nf
struct xxcontext cur_ctx;
static int
xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
	size_t len, uint_t type, uint_t rw)
{
    devmap_cookie_t cur_dhp;
    struct xxpvtdata *p;
    struct xxpvtdata *pvp = (struct xxpvtdata *)pvtp;
    struct xx_softc  *softc = pvp->softc;
    int    err;

    mutex_enter(&softc->mutex);

    /*
     * invalidate the translations of current context before
     * switching context.
     */
    if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
        p = cur_ctx->pvt;
        cur_dhp = p->dhp;
        if ((err = devmap_unload(cur_dhp, off, len)) != 0)
            return (err);
    }
    /* Switch device context - device dependent*/
    ...
    /* Make handle the new current mapping */
    cur_ctx = pvp->ctx;

    /*
     * Load the address translations of the calling context.
     */
    err = devmap_load(pvp->dhp, off, len, type, rw);

    mutex_exit(&softc->mutex);

    return (err);
}
.fi
.in -2

.SH SEE ALSO
\fBdevmap_access\fR(9E), \fBdevmap_do_ctxmgt\fR(9F) \fBdevmap_load\fR(9F),
.BR devmap_unload (9F)
.sp
.LP
\fIWriting Device Drivers\fR