devmap_access(9e)

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

NAME

6       devmap_access - device mapping access entry point
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int prefixdevmap_access(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                DEVMAP_EXEC      Execution access attempted.
57
58
59

DESCRIPTION

61       The  devmap_access()  entry  point is an optional routine.  It notifies
62       drivers whenever an access is made to a mapping described by  dhp  that
63       has  not been validated or does  not have sufficient protection for the
64       access.   The   system   expects   devmap_access()   to   call   either
65       devmap_do_ctxmgt(9F)  or  devmap_default_access(9F)  to load the memory
66       address translations before it returns. For mappings that support  con‐
67       text  switching,   device drivers should call devmap_do_ctxmgt(9F). For
68       mappings that do not support context switching, the drivers should call
69       devmap_default_access(9F).
70
71
72       In   devmap_access(),  drivers perform memory access related operations
73       such as context switching, checking  the  availability  of  the  memory
74       object, and locking and unlocking the memory object being accessed. The
75       devmap_access() entry point is set to  NULL if no operations need to be
76       performed.
77
78
79       pvtp  is  a pointer to the driver's private mapping data that was allo‐
80       cated and initialized in the devmap_map(9E) entry point.
81
82
83       off and len define the range  to  be  affected  by  the  operations  in
84       devmap_access(). type defines the type of operation that device drivers
85       should perform on the memory object.  If type is either DEVMAP_LOCK  or
86       DEVMAP_UNLOCK,  the  length  passed  to  either devmap_do_ctxmgt(9F) or
87       devmap_default_access(9F) must be same as  len. rw specifies the direc‐
88       tion of access on the memory object.
89
90
91       A  non-zero  return value from  devmap_access() may result in a SIGSEGV
92       or SIGBUS signal being delivered to the process.
93

RETURN VALUES

95       devmap_access() returns the following values:
96
97       0           Successful completion.
98
99
100       Non-zero    An    error    occurred.     The    return    value    from
101                   devmap_do_ctxmgt(9F) or devmap_default_access(9F) should be
102                   returned.
103
104

EXAMPLES

106       Example 1 devmap_access() entry point
107
108
109       The following is an example of the devmap_access() entry point.  If the
110       mapping    supports    context    switching,    devmap_access()   calls
111       devmap_do_ctxmgt(9F).      Otherwise,       devmap_access()       calls
112       devmap_default_access(9F).
113
114
115         ...
116         #define OFF_DO_CTXMGT  0x40000000
117         #define OFF_NORMAL     0x40100000
118         #define CTXMGT_SIZE    0x100000
119         #define NORMAL_SIZE    0x100000
120
121         /*
122          * Driver devmap_contextmgt(9E) callback function.
123          */
124         static int
125         xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset,
126            size_t length, uint_t type, uint_t rw)
127         {
128            ......
129            /*
130             * see devmap_contextmgt(9E) for an example
131             */
132         }
133
134         /*
135          * Driver devmap_access(9E) entry point
136          */
137         static int
138         xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off,
139            size_t len, uint_t type, uint_t rw)
140         {
141            offset_t diff;
142            int err;
143
144            /*
145             * check if off is within the range that supports
146             * context management.
147             */
148            if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) {
149                /*
150                 * calculates the length for context switching
151                 */
152                if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE))
153                    return (-1);
154                /*
155                 * perform context switching
156                 */
157                err = devmap_do_ctxmgt(dhp, pvtp, off, len, type,
158                    rw, xx_context_mgt);
159             /*
160              * check if  off is within the range that does normal
161              * memory mapping.
162              */
163             } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) {
164                if ((len + off) > (OFF_NORMAL + NORMAL_SIZE))
165                    return (-1);
166                err = devmap_default_access(dhp, pvtp, off, len, type, rw);
167             } else
168                return (-1);
169
170            return (err);
171         }
172
173