devmap_do_ctxmgt(9f)

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

NAME

6       devmap_do_ctxmgt - perform device context switching on a mapping
7

SYNOPSIS

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

INTERFACE LEVEL

21       Solaris DDI specific (Solaris DDI).
22

PARAMETERS

24       dhp                   An  opaque mapping handle that the system uses to
25                             describe the mapping.
26
27
28       pvtp                  Driver private mapping data.
29
30
31       off                   User offset within the logical device  memory  at
32                             which the access begins.
33
34
35       len                   Length (in bytes) of the memory being accessed.
36
37
38       devmap_contextmgt     The  address  of  driver function that the system
39                             will call to perform context switching on a  map‐
40                             ping. See devmap_contextmgt(9E) for details.
41
42
43       type                  Type    of   access   operation.    Provided   by
44                             devmap_access(9E). Should not be modified.
45
46
47       rw                    Direction     of     access.      Provided     by
48                             devmap_access(9E). Should not be modified.
49
50

DESCRIPTION

52       Device  drivers  call devmap_do_ctxmgt() in the devmap_access(9E) entry
53       point   to   perform   device   context   switching   on   a   mapping.
54       devmap_do_ctxmgt() passes a pointer to a driver supplied callback func‐
55       tion, devmap_contextmgt(9E), to the system that will perform the actual
56       device  context  switching.   If  devmap_contextmgt(9E)  is not a valid
57       driver callback function, the system will fail the memory access opera‐
58       tion which will result in a SIGSEGV or SIGBUS signal being delivered to
59       the process.
60
61
62       devmap_do_ctxmgt() performs context switching  on  the  mapping  object
63       identified  by  dhp and pvtp in the range specified by off and len. The
64       arguments dhp, pvtp, type, and rw are provided by the devmap_access(9E)
65       entry  point  and  must  not be modified. The range from off to off+len
66       must support context switching.
67
68
69       The system will pass through dhp, pvtp, off,   len,  type,  and  rw  to
70       devmap_contextmgt(9E)  in  order  to  perform the actual device context
71       switching.   The  return  value  from  devmap_contextmgt(9E)  will   be
72       returned directly to devmap_do_ctxmgt().
73

RETURN VALUES

75       0           Successful completion.
76
77
78       Non-zero    An error occurred.
79
80

CONTEXT

82       devmap_do_ctxmgt()  must  be called from the driver's devmap_access(9E)
83       entry point.
84

EXAMPLES

86       Example 1 Using devmap_do_ctxmgt in the devmap_access entry point.
87
88
89       The following shows an  example  of  using  devmap_do_ctxmgt()  in  the
90       devmap_access(9E) entry point.
91
92
93         ...
94         #define OFF_DO_CTXMGT  0x40000000
95         #define OFF_NORMAL     0x40100000
96         #define CTXMGT_SIZE    0x100000
97         #define NORMAL_SIZE    0x100000
98
99         /*
100          * Driver devmap_contextmgt(9E) callback function.
101          */
102         static int
103         xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset,
104             size_t length, uint_t type, uint_t rw)
105         {
106             ......
107             /*
108              * see devmap_contextmgt(9E) for an example
109              */
110         }
111
112         /*
113          * Driver devmap_access(9E) entry point
114          */
115         static int
116         xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off,
117             size_t len, uint_t type, uint_t rw)
118         {
119             offset_t diff;
120             int err;
121
122             /*
123              * check if off is within the range that supports
124              * context management.
125              */
126             if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) {
127                 /*
128                  * calculates the length for context switching
129                  */
130                 if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE))
131                     return (-1);
132                 /*
133                  * perform context switching
134                  */
135                 err = devmap_do_ctxmgt(dhp, pvtp, off, len, type,
136                             rw, xx_context_mgt);
137             /*
138              * check if off is within the range that does normal
139              * memory mapping.
140              */
141             } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) {
142                 if ((len + off) > (OFF_NORMAL + NORMAL_SIZE))
143                     return (-1);
144                 err = devmap_default_access(dhp, pvtp, off, len, type, rw);
145             } else
146                 return (-1);
147
148             return (err);
149         }
150
151