devmap_unload(9f)

1devmap_unload(9F)        Kernel Functions for Drivers        devmap_unload(9F)
2
3
4

NAME

6       devmap_unload,  devmap_load  -  control  validation  of  memory address
7       translations
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int devmap_load(devmap_cookie_t dhp, offset_t off, size_t len,
16            uint_t type, uint_t rw);
17
18
19       int devmap_unload(devmap_cookie_t dhp, offset_t off, size_t len);
20
21

INTERFACE LEVEL

23       Solaris DDI specific (Solaris DDI).
24

PARAMETERS

26       dhp     An opaque mapping handle that the system uses to  describe  the
27               mapping.
28
29
30       off     User offset within the logical device memory at which the load‐
31               ing or unloading of the address translations begins.
32
33
34       len     Length (in bytes) of the range being affected.
35
36
37   devmap_load() only
38       type     Type of access operation.
39
40
41       rw       Direction of access.
42
43

DESCRIPTION

45       devmap_unload() and devmap_load() are used to control the validation of
46       the   memory   mapping   described  by  dhp  in  the  specified  range.
47       devmap_unload() invalidates the mapping translations and will  generate
48       calls  to  the  devmap_access(9E)  entry point next time the mapping is
49       accessed. The drivers use devmap_load() to validate the mapping  trans‐
50       lations during memory access.
51
52
53       A  typical  use of devmap_unload() and devmap_load() is in the driver's
54       context management callback function, devmap_contextmgt(9E). To  manage
55       a  device context, a device driver calls devmap_unload() on the context
56       about to  be  switched  out.  It  switches  contexts,  and  then  calls
57       devmap_load() on the context switched in.   devmap_unload() can be used
58       to unload the mappings of other processes as well as  the  mappings  of
59       the  calling  process,  but  devmap_load() can only be used to load the
60       mappings of the calling process. Attempting to load  another  process's
61       mappings with devmap_load() will result in a system panic.
62
63
64       For  both  routines, the range to be affected is defined by the off and
65       len arguments. Requests affect the entire page containing the  off  and
66       all  pages  up  to  and  including the page containing the last byte as
67       indicated by off + len. The arguments type and rw are provided  by  the
68       system to the calling function (for example, devmap_contextmgt(9E)) and
69       should not be modified.
70
71
72       Supplying a value of  0 for the len argument affects all addresses from
73       the  off to the end of the mapping.  Supplying a value of 0 for the off
74       argument and a value of 0 for len argument affect all addresses in  the
75       mapping.
76
77
78       A  non-zero  return  value from either devmap_unload() or devmap_load()
79       will cause the corresponding operation to fail. The failure may  result
80       in a SIGSEGV or SIGBUS signal being delivered to the process.
81

RETURN VALUES

83       0           Successful completion.
84
85
86       Non-zero    An error occurred.
87
88

CONTEXT

90       These routines can be called from user or kernel context only.
91

EXAMPLES

93       Example 1 Managing a One-Page Device Context
94
95
96       The following shows an example of managing a device context that is one
97       page in length.
98
99
100         struct xx_context cur_ctx;
101
102         static int
103         xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
104            size_t len, uint_t type, uint_t rw)
105         {
106             int err;
107             devmap_cookie_t cur_dhp;
108             struct xx_pvt *p;
109             struct xx_pvt *pvp = (struct xx_pvt *)pvtp;
110             /* enable access callbacks for the current mapping */
111             if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
112                 p = cur_ctx->pvt;
113                 /*
114                  * unload the region from off to the end of the mapping.
115                  */
116                 cur_dhp = p->dhp;
117                 if ((err = devmap_unload(cur_dhp, off, len)) != 0)
118                     return (err);
119             }
120             /* Switch device context - device dependent*/
121             ...
122             /* Make handle the new current mapping */
123             cur_ctx = pvp->ctx;
124             /*
125              * Disable callbacks and complete the access for the
126              * mapping that generated this callback.
127              */
128             return (devmap_load(pvp->dhp, off, len, type, rw));
129         }
130
131