Current File : //usr/man/man9e/devmap_contextmgt.9e

'\" te
.\"  Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.TH devmap_contextmgt 9E "16 Jan 1997" "SunOS 5.11" "Driver Entry Points"
.SH NAME
devmap_contextmgt \- driver callback function for context management
.SH SYNOPSIS
.LP
.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
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH ARGUMENTS
.sp
.ne 2
.mk
.na
\fB\fIdhp\fR \fR
.ad
.RS 9n
.rt  
An opaque mapping handle that the system uses to describe the mapping.
.RE

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

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

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

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

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

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

.RE

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

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

.RE

.SH DESCRIPTION
.sp
.LP
\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
.sp
.ne 2
.mk
.na
\fB\fB0\fR \fR
.ad
.RS 12n
.rt  
Successful completion.
.RE

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

.SH EXAMPLES
.LP
\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
.sp
.LP
\fBdevmap_access\fR(9E), \fBdevmap_do_ctxmgt\fR(9F) \fBdevmap_load\fR(9F), \fBdevmap_unload\fR(9F) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR