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

NAME

6       devmap_devmem_setup,  devmap_umem_setup  -  set  driver  memory mapping
7       parameters
8

SYNOPSIS

10       #include <sys/ddi.h>
11       #include <sys/sunddi.h>
12
13
14
15       int devmap_devmem_setup(devmap_cookie_t dhp, dev_info_t *dip,
16            struct devmap_callback_ctl *callbackops, uint_t rnumber,
17            offset_t roff,  size_t len, uint_t maxprot,
18            uint_t flags, ddi_device_acc_attr_t *accattrp);
19
20
21       int devmap_umem_setup(devmap_cookie_t dhp, dev_info_t *dip,
22            struct devmap_callback_ctl *callbackops, ddi_umem_cookie_t cookie,
23            offset_t koff, size_t len, uint_t maxprot, uint_t flags,
24            ddi_device_acc_attr_t *accattrp);
25
26

INTERFACE LEVEL

28       Solaris DDI specific (Solaris DDI).
29

PARAMETERS

31       devmap_devmem_setup() parameters:
32
33       dhp            An  opaque  mapping  handle  that  the  system  uses  to
34                      describe the mapping.
35
36
37       dip            Pointer to the device's dev_info structure.
38
39
40       callbackops    Pointer  to  a  devmap_callback_ctl(9S)  structure.  The
41                      structure contains pointers  to  device  driver-supplied
42                      functions  that manage events on the device mapping. The
43                      framework will copy the structure to the system  private
44                      memory.
45
46
47       rnumber        Index number to the register address space set.
48
49
50       roff           Offset into the register address space.
51
52
53       len            Length (in bytes) of the mapping to be mapped.
54
55
56       maxprot        Maximum  protection flag possible for attempted mapping.
57                      Some combinations of possible settings are:
58
59                      PROT_READ     Read access is allowed.
60
61
62                      PROT_WRITE    Write access is allowed.
63
64
65                      PROT_EXEC     Execute access is allowed.
66
67
68                      PROT_USER     User-level access is allowed. The  mapping
69                                    is  done  as  a result of a mmap(2) system
70                                    call.
71
72
73                      PROT_ALL      All access is allowed.
74
75
76
77       flags          Used to determine the cache attribute.
78
79                      Possible values of the cache attribute are:
80
81                      IOMEM_DATA_CACHED           The CPU can cache  the  data
82                                                  it  fetches  and  push it to
83                                                  memory at a later time. This
84                                                  is   the  default  attribute
85                                                  that is  used  if  no  cache
86                                                  attributes are specified.
87
88
89                      IOMEM_DATA_UC_WR_COMBINE    The  CPU  never  caches  the
90                                                  data, but writes  can  occur
91                                                  out  of order or can be com‐
92                                                  bined.     Reordering     is
93                                                  implied.
94
95                                                  If  IOMEM_DATA_UC_WR_COMBINE
96                                                  is specified  but  not  sup‐
97                                                  ported,  IOMEM_DATA_UNCACHED
98                                                  is used instead.
99
100
101                      IOMEM_DATA_UNCACHED         The CPU never  caches  data,
102                                                  but  has  uncacheable access
103                                                  to memory.  Strict  ordering
104                                                  is implied.
105
106                      The  cache attributes are mutually exclusive. Any combi‐
107                      nation of the values leads to a failure.  On  the  SPARC
108                      architecture, only IOMEM_DATA_CACHED is meaningful. Oth‐
109                      ers lead to a failure.
110
111
112       accattrp       Pointer to  a  ddi_device_acc_attr()  structure  of  the
113                      device.   See   ddi_device_acc_attr(9S).  The  value  in
114                      devacc_attr_dataorder is ignored in the current release.
115                      The  value  in devacc_attr_endian_flags is meaningful on
116                      the SPARC architecture only.
117
118
119
120       devmap_umem_setup() parameters:
121
122       dhp            An  opaque  data  structure  that  the  system  uses  to
123                      describe the mapping.
124
125
126       dip            Pointer to the device's dev_info structure.
127
128
129       callbackops    Pointer  to  a  devmap_callback_ctl(9S)  structure.  The
130                      structure contains pointers  to  device  driver-supplied
131                      functions that manage events on the device mapping.
132
133
134       cookie         A kernel memory cookie (see ddi_umem_alloc(9F)).
135
136
137       koff           Offset into the kernel memory defined by cookie.
138
139
140       len            Length (in bytes) of the mapping to be mapped.
141
142
143       maxprot        Maximum  protection flag possible for attempted mapping.
144                      Some combinations of possible settings are:
145
146                      PROT_READ     Read access is allowed.
147
148
149                      PROT_WRITE    Write access is allowed.
150
151
152                      PROT_EXEC     Execute access is allowed.
153
154
155                      PROT_USER     User-level access is allowed (the  mapping
156                                    is  being  done  as  a result of a mmap(2)
157                                    system call).
158
159
160                      PROT_ALL      All access is allowed.
161
162
163
164       flags          Must be set to 0.
165
166
167       accattrp       Pointer to a ddi_device_acc_attr(9S) structure.  Ignored
168                      in the current release. Reserved for future use.
169
170

DESCRIPTION

172       The devmap_devmem_setup() and devmap_umem_setup() functions are used in
173       the devmap(9E) entry point to pass mapping parameters from  the  driver
174       to the system.
175
176
177       The dhp argument specifies a device mapping handle that the system uses
178       to store all mapping parameters of a physical  contiguous  memory.  The
179       system  copies  the  data pointed to by callbackops to a system private
180       memory. This allows the driver to free the data  after  returning  from
181       either  devmap_devmem_setup()  or  devmap_umem_setup().  The  driver is
182       notified of user events on the mappings via the entry points defined by
183       devmap_callback_ctl(9S).  The  driver is notified of the following user
184       events:
185
186       Mapping Setup    User has called mmap(2) to create  a  mapping  to  the
187                        device memory.
188
189
190       Access           User  has  accessed an address in the mapping that has
191                        no translations.
192
193
194       Duplication      User has duplicated the mapping. Mappings  are  dupli‐
195                        cated when the process calls fork(2).
196
197
198       Unmapping        User  has  called munmap(2) on the mapping or is exit‐
199                        ing, exit(2).
200
201
202
203       See    devmap_map(9E),    devmap_access(9E),    devmap_dup(9E),     and
204       devmap_unmap(9E) for details on these entry points.
205
206
207       By  specifying  a  valid  callbackops to the system, device drivers can
208       manage events on a device mapping. For example,  the  devmap_access(9E)
209       entry  point allows the drivers to perform context switching by unload‐
210       ing the mappings of other processes and to  load  the  mapping  of  the
211       calling  process.  Device drivers may specify NULL to callbackops which
212       means the drivers do not want to be notified by the system.
213
214
215       The maximum protection allowed for the mapping is specified in maxprot.
216       accattrp     defines     the     device    access    attributes.    See
217       ddi_device_acc_attr(9S) for more details.
218
219
220       devmap_devmem_setup() is used for device memory to map in the  register
221       set  given  by  rnumber  and the offset into the register address space
222       given by roff. The system uses rnumber and roff to  go  up  the  device
223       tree to get the physical address that corresponds to roff. The range to
224       be affected is defined by len and roff. The range from roff to  roff  +
225       len must be a physical contiguous memory and page aligned.
226
227
228       Drivers  use devmap_umem_setup() for kernel memory to map in the kernel
229       memory described by cookie and the offset into the kernel memory  space
230       given  by  koff.  cookie  is  a  kernel  memory  pointer  obtained from
231       ddi_umem_alloc(9F). If cookie is NULL, devmap_umem_setup() returns  -1.
232       The  range  to  be  affected is defined by len and koff. The range from
233       koff to koff + len must be within  the  limits  of  the  kernel  memory
234       described by koff + len and must be page aligned.
235
236
237       Drivers  use  devmap_umem_setup() to export the kernel memory allocated
238       by ddi_umem_alloc(9F) to user space. The system selects a user  virtual
239       address that is aligned with the kernel virtual address being mapped to
240       avoid cache incoherence if the mapping is not MAP_FIXED.
241

RETURN VALUES

243       0     Successful completion.
244
245
246       -1    An error occurred.
247
248

CONTEXT

250       devmap_devmem_setup() and devmap_umem_setup() can be called from  user,
251       kernel, and interrupt context.
252

SEE ALSO

254       exit(2),  fork(2),  mmap(2), munmap(2), devmap(9E), ddi_umem_alloc(9F),
255       ddi_device_acc_attr(9S), devmap_callback_ctl(9S)
256
257
258       Writing Device Drivers
259
260
261
262SunOS 5.11                        05 Jun 2006          devmap_devmem_setup(9F)
Impressum