devmap_contextmgt(9e)

1devmap_contextmgt(9E)         Driver Entry Points        devmap_contextmgt(9E)
2
3
4

NAME

6       devmap_contextmgt - driver callback function for context management
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int devmap_contextmgt(devmap_cookie_t dhp, void *pvtp,
15            offset_t off, size_t len, uint_t type, uint_t rw);
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI).
20

ARGUMENTS

22       dhp      An  opaque mapping handle that the system uses to describe the
23                mapping.
24
25
26       pvtp     Driver private mapping data.
27
28
29       off      User offset within the logical  device  memory  at  which  the
30                access begins.
31
32
33       len      Length (in bytes) of the memory being accessed.
34
35
36       type     Type of access operation. Possible values are:
37
38                DEVMAP_ACCESS     Memory access.
39
40
41                DEVMAP_LOCK       Lock the memory being accessed.
42
43
44                DEVMAP_UNLOCK     Unlock the memory being accessed.
45
46
47
48       rw       Direction of access. Possible values are:
49
50                DEVMAP_READ      Read access attempted.
51
52
53                DEVMAP_WRITE     Write access attempted.
54
55
56

DESCRIPTION

58       devmap_contextmgt()  is a driver-supplied function that performs device
59       context switching on  a   mapping.   Device  drivers  pass  devmap_con‐
60       textmgt()    as    an   argument   to   devmap_do_ctxmgt(9F)   in   the
61       devmap_access(9E) entry point. The system will call devmap_contextmgt()
62       when  memory  is  accessed.  The system expects  devmap_contextmgt() to
63       load  the  memory  address  translations  of  the  mapping  by  calling
64       devmap_load(9F) before returning.
65
66
67       dhp  uniquely  identifies  the  mapping  and  is used as an argument to
68       devmap_load(9F) to validate the mapping. off and len define  the  range
69       to be affected by the operations in devmap_contextmgt().
70
71
72       The  driver must check if there is already a mapping established at off
73       that needs to be unloaded. If a  mapping  exists  at  off,  devmap_con‐
74       textmgt()   must   call   devmap_unload(9F)  on  the  current  mapping.
75       devmap_unload(9F) must be followed by devmap_load() on the mapping that
76       generated  this  call to devmap_contextmgt(). devmap_unload(9F) unloads
77       the current mapping so that a call to devmap_access(9E),  which  causes
78       the system to call devmap_contextmgt(), will be generated the next time
79       the mapping is accessed.
80
81
82       pvtp is a pointer to the driver's private mapping data that  was  allo‐
83       cated  and  initialized in the devmap_map(9E) entry point. type defines
84       the type of operation that device drivers should perform on the  memory
85       object.   If  type  is  either DEVMAP_LOCK or DEVMAP_UNLOCK, the length
86       passed to either devmap_unload(9F) or devmap_load(9F) must be  same  as
87       len. rw specifies the access direction on the memory object.
88
89
90       A  non-zero  return value from  devmap_contextmgt() will be returned to
91       devmap_access(9E) and will cause the corresponding operation  to  fail.
92       The failure may result in a SIGSEGV or SIGBUS signal being delivered to
93       the process.
94

RETURN VALUES

96       0           Successful completion.
97
98
99       Non-zero    An error occurred.
100
101

EXAMPLES

103       Example 1 managing a device context
104
105
106       The following shows an example of managing a device context.
107
108
109         struct xxcontext cur_ctx;
110         static int
111         xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
112              size_t len, uint_t type, uint_t rw)
113         {
114             devmap_cookie_t cur_dhp;
115             struct xxpvtdata *p;
116             struct xxpvtdata *pvp = (struct xxpvtdata *)pvtp;
117             struct xx_softc  *softc = pvp->softc;
118             int    err;
119
120             mutex_enter(&softc->mutex);
121
122             /*
123              * invalidate the translations of current context before
124              * switching context.
125              */
126             if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
127                 p = cur_ctx->pvt;
128                 cur_dhp = p->dhp;
129                 if ((err = devmap_unload(cur_dhp, off, len)) != 0)
130                     return (err);
131             }
132             /* Switch device context - device dependent*/
133             ...
134             /* Make handle the new current mapping */
135             cur_ctx = pvp->ctx;
136
137             /*
138              * Load the address translations of the calling context.
139              */
140             err = devmap_load(pvp->dhp, off, len, type, rw);
141
142             mutex_exit(&softc->mutex);
143
144             return (err);
145         }
146
147