1devmap_devmem_setup(9F) Kernel Functions for Drivers devmap_devmem_setup(9F)
2
6 devmap_devmem_setup, devmap_umem_setup - set driver memory mapping
7 parameters
8
10 #include <sys/ddi.h>
11 #include <sys/sunddi.h>
12 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 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
28 Solaris DDI specific (Solaris DDI).
29
31 devmap_devmem_setup() parameters:
32 dhp An opaque mapping handle that the system uses to
34 describe the mapping.
35 dip Pointer to the device's dev_info structure.
38 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 rnumber Index number to the register address space set.
48 roff Offset into the register address space.
51 len Length (in bytes) of the mapping to be mapped.
54 maxprot Maximum protection flag possible for attempted mapping.
57 Some combinations of possible settings are:
58 PROT_READ Read access is allowed.
60 PROT_WRITE Write access is allowed.
63 PROT_EXEC Execute access is allowed.
66 PROT_USER User-level access is allowed. The mapping
69 is done as a result of a mmap(2) system
70 call.
71 PROT_ALL All access is allowed.
74 flags Used to determine the cache attribute.
78 Possible values of the cache attribute are:
80 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 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 If IOMEM_DATA_UC_WR_COMBINE
96 is specified but not sup‐
97 ported, IOMEM_DATA_UNCACHED
98 is used instead.
99 IOMEM_DATA_UNCACHED The CPU never caches data,
102 but has uncacheable access
103 to memory. Strict ordering
104 is implied.
105 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 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 devmap_umem_setup() parameters:
121 dhp An opaque data structure that the system uses to
123 describe the mapping.
124 dip Pointer to the device's dev_info structure.
127 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 cookie A kernel memory cookie (see ddi_umem_alloc(9F)).
135 koff Offset into the kernel memory defined by cookie.
138 len Length (in bytes) of the mapping to be mapped.
141 maxprot Maximum protection flag possible for attempted mapping.
144 Some combinations of possible settings are:
145 PROT_READ Read access is allowed.
147 PROT_WRITE Write access is allowed.
150 PROT_EXEC Execute access is allowed.
153 PROT_USER User-level access is allowed (the mapping
156 is being done as a result of a mmap(2)
157 system call).
158 PROT_ALL All access is allowed.
161 flags Must be set to 0.
165 accattrp Pointer to a ddi_device_acc_attr(9S) structure. Ignored
168 in the current release. Reserved for future use.
169
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 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 Mapping Setup User has called mmap(2) to create a mapping to the
187 device memory.
188 Access User has accessed an address in the mapping that has
191 no translations.
192 Duplication User has duplicated the mapping. Mappings are dupli‐
195 cated when the process calls fork(2).
196 Unmapping User has called munmap(2) on the mapping or is exit‐
199 ing, exit(2).
200 See devmap_map(9E), devmap_access(9E), devmap_dup(9E), and
204 devmap_unmap(9E) for details on these entry points.
205 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 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 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 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 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
243 0 Successful completion.
244 -1 An error occurred.
247
250 devmap_devmem_setup() and devmap_umem_setup() can be called from user,
251 kernel, and interrupt context.
252
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 Writing Device Drivers
259SunOS 5.11 05 Jun 2006 devmap_devmem_setup(9F)