Commit | Line | Data |
---|---|---|
8a8a602f JC |
1 | .. Copyright 2001 Matthew Wilcox |
2 | .. | |
3 | .. This documentation is free software; you can redistribute | |
4 | .. it and/or modify it under the terms of the GNU General Public | |
5 | .. License as published by the Free Software Foundation; either | |
6 | .. version 2 of the License, or (at your option) any later | |
7 | .. version. | |
8 | ||
9 | =============================== | |
10 | Bus-Independent Device Accesses | |
11 | =============================== | |
12 | ||
13 | :Author: Matthew Wilcox | |
14 | :Author: Alan Cox | |
15 | ||
16 | Introduction | |
17 | ============ | |
18 | ||
19 | Linux provides an API which abstracts performing IO across all busses | |
20 | and devices, allowing device drivers to be written independently of bus | |
21 | type. | |
22 | ||
23 | Memory Mapped IO | |
24 | ================ | |
25 | ||
26 | Getting Access to the Device | |
27 | ---------------------------- | |
28 | ||
29 | The most widely supported form of IO is memory mapped IO. That is, a | |
30 | part of the CPU's address space is interpreted not as accesses to | |
31 | memory, but as accesses to a device. Some architectures define devices | |
32 | to be at a fixed address, but most have some method of discovering | |
33 | devices. The PCI bus walk is a good example of such a scheme. This | |
34 | document does not cover how to receive such an address, but assumes you | |
35 | are starting with one. Physical addresses are of type unsigned long. | |
36 | ||
37 | This address should not be used directly. Instead, to get an address | |
38 | suitable for passing to the accessor functions described below, you | |
3a63e9fc | 39 | should call ioremap(). An address suitable for accessing |
8a8a602f JC |
40 | the device will be returned to you. |
41 | ||
42 | After you've finished using the device (say, in your module's exit | |
3a63e9fc | 43 | routine), call iounmap() in order to return the address |
8a8a602f | 44 | space to the kernel. Most architectures allocate new address space each |
3a63e9fc PM |
45 | time you call ioremap(), and they can run out unless you |
46 | call iounmap(). | |
8a8a602f JC |
47 | |
48 | Accessing the device | |
49 | -------------------- | |
50 | ||
51 | The part of the interface most used by drivers is reading and writing | |
52 | memory-mapped registers on the device. Linux provides interfaces to read | |
53 | and write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a | |
54 | historical accident, these are named byte, word, long and quad accesses. | |
55 | Both read and write accesses are supported; there is no prefetch support | |
56 | at this time. | |
57 | ||
58 | The functions are named readb(), readw(), readl(), readq(), | |
59 | readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), | |
60 | writeb(), writew(), writel() and writeq(). | |
61 | ||
62 | Some devices (such as framebuffers) would like to use larger transfers than | |
3a63e9fc PM |
63 | 8 bytes at a time. For these devices, the memcpy_toio(), |
64 | memcpy_fromio() and memset_io() functions are | |
8a8a602f JC |
65 | provided. Do not use memset or memcpy on IO addresses; they are not |
66 | guaranteed to copy data in order. | |
67 | ||
68 | The read and write functions are defined to be ordered. That is the | |
69 | compiler is not permitted to reorder the I/O sequence. When the ordering | |
70 | can be compiler optimised, you can use __readb() and friends to | |
71 | indicate the relaxed ordering. Use this with care. | |
72 | ||
73 | While the basic functions are defined to be synchronous with respect to | |
74 | each other and ordered with respect to each other the busses the devices | |
75 | sit on may themselves have asynchronicity. In particular many authors | |
76 | are burned by the fact that PCI bus writes are posted asynchronously. A | |
77 | driver author must issue a read from the same device to ensure that | |
78 | writes have occurred in the specific cases the author cares. This kind | |
79 | of property cannot be hidden from driver writers in the API. In some | |
80 | cases, the read used to flush the device may be expected to fail (if the | |
81 | card is resetting, for example). In that case, the read should be done | |
82 | from config space, which is guaranteed to soft-fail if the card doesn't | |
83 | respond. | |
84 | ||
85 | The following is an example of flushing a write to a device when the | |
86 | driver would like to ensure the write's effects are visible prior to | |
87 | continuing execution:: | |
88 | ||
89 | static inline void | |
90 | qla1280_disable_intrs(struct scsi_qla_host *ha) | |
91 | { | |
92 | struct device_reg *reg; | |
93 | ||
94 | reg = ha->iobase; | |
95 | /* disable risc and host interrupts */ | |
96 | WRT_REG_WORD(®->ictrl, 0); | |
97 | /* | |
98 | * The following read will ensure that the above write | |
99 | * has been received by the device before we return from this | |
100 | * function. | |
101 | */ | |
102 | RD_REG_WORD(®->ictrl); | |
103 | ha->flags.ints_enabled = 0; | |
104 | } | |
105 | ||
8a8a602f JC |
106 | PCI ordering rules also guarantee that PIO read responses arrive after any |
107 | outstanding DMA writes from that bus, since for some devices the result of | |
108 | a readb() call may signal to the driver that a DMA transaction is | |
109 | complete. In many cases, however, the driver may want to indicate that the | |
110 | next readb() call has no relation to any previous DMA writes | |
111 | performed by the device. The driver can use readb_relaxed() for | |
112 | these cases, although only some platforms will honor the relaxed | |
113 | semantics. Using the relaxed read functions will provide significant | |
114 | performance benefits on platforms that support it. The qla2xxx driver | |
115 | provides examples of how to use readX_relaxed(). In many cases, a majority | |
116 | of the driver's readX() calls can safely be converted to readX_relaxed() | |
117 | calls, since only a few will indicate or depend on DMA completion. | |
118 | ||
119 | Port Space Accesses | |
120 | =================== | |
121 | ||
122 | Port Space Explained | |
123 | -------------------- | |
124 | ||
125 | Another form of IO commonly supported is Port Space. This is a range of | |
126 | addresses separate to the normal memory address space. Access to these | |
127 | addresses is generally not as fast as accesses to the memory mapped | |
128 | addresses, and it also has a potentially smaller address space. | |
129 | ||
130 | Unlike memory mapped IO, no preparation is required to access port | |
131 | space. | |
132 | ||
133 | Accessing Port Space | |
134 | -------------------- | |
135 | ||
136 | Accesses to this space are provided through a set of functions which | |
137 | allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and | |
3a63e9fc PM |
138 | long. These functions are inb(), inw(), |
139 | inl(), outb(), outw() and | |
140 | outl(). | |
8a8a602f JC |
141 | |
142 | Some variants are provided for these functions. Some devices require | |
143 | that accesses to their ports are slowed down. This functionality is | |
144 | provided by appending a ``_p`` to the end of the function. | |
3a63e9fc PM |
145 | There are also equivalents to memcpy. The ins() and |
146 | outs() functions copy bytes, words or longs to the given | |
8a8a602f JC |
147 | port. |
148 | ||
eeba4b01 AB |
149 | __iomem pointer tokens |
150 | ====================== | |
151 | ||
152 | The data type for an MMIO address is an ``__iomem`` qualified pointer, such as | |
153 | ``void __iomem *reg``. On most architectures it is a regular pointer that | |
154 | points to a virtual memory address and can be offset or dereferenced, but in | |
155 | portable code, it must only be passed from and to functions that explicitly | |
156 | operated on an ``__iomem`` token, in particular the ioremap() and | |
157 | readl()/writel() functions. The 'sparse' semantic code checker can be used to | |
158 | verify that this is done correctly. | |
159 | ||
160 | While on most architectures, ioremap() creates a page table entry for an | |
161 | uncached virtual address pointing to the physical MMIO address, some | |
162 | architectures require special instructions for MMIO, and the ``__iomem`` pointer | |
163 | just encodes the physical address or an offsettable cookie that is interpreted | |
164 | by readl()/writel(). | |
165 | ||
166 | Differences between I/O access functions | |
167 | ======================================== | |
168 | ||
169 | readq(), readl(), readw(), readb(), writeq(), writel(), writew(), writeb() | |
170 | ||
171 | These are the most generic accessors, providing serialization against other | |
172 | MMIO accesses and DMA accesses as well as fixed endianness for accessing | |
173 | little-endian PCI devices and on-chip peripherals. Portable device drivers | |
174 | should generally use these for any access to ``__iomem`` pointers. | |
175 | ||
176 | Note that posted writes are not strictly ordered against a spinlock, see | |
177 | Documentation/driver-api/io_ordering.rst. | |
178 | ||
179 | readq_relaxed(), readl_relaxed(), readw_relaxed(), readb_relaxed(), | |
180 | writeq_relaxed(), writel_relaxed(), writew_relaxed(), writeb_relaxed() | |
181 | ||
182 | On architectures that require an expensive barrier for serializing against | |
183 | DMA, these "relaxed" versions of the MMIO accessors only serialize against | |
184 | each other, but contain a less expensive barrier operation. A device driver | |
185 | might use these in a particularly performance sensitive fast path, with a | |
186 | comment that explains why the usage in a specific location is safe without | |
187 | the extra barriers. | |
188 | ||
189 | See memory-barriers.txt for a more detailed discussion on the precise ordering | |
190 | guarantees of the non-relaxed and relaxed versions. | |
191 | ||
192 | ioread64(), ioread32(), ioread16(), ioread8(), | |
193 | iowrite64(), iowrite32(), iowrite16(), iowrite8() | |
194 | ||
195 | These are an alternative to the normal readl()/writel() functions, with almost | |
196 | identical behavior, but they can also operate on ``__iomem`` tokens returned | |
197 | for mapping PCI I/O space with pci_iomap() or ioport_map(). On architectures | |
198 | that require special instructions for I/O port access, this adds a small | |
199 | overhead for an indirect function call implemented in lib/iomap.c, while on | |
200 | other architectures, these are simply aliases. | |
201 | ||
202 | ioread64be(), ioread32be(), ioread16be() | |
203 | iowrite64be(), iowrite32be(), iowrite16be() | |
204 | ||
205 | These behave in the same way as the ioread32()/iowrite32() family, but with | |
206 | reversed byte order, for accessing devices with big-endian MMIO registers. | |
207 | Device drivers that can operate on either big-endian or little-endian | |
208 | registers may have to implement a custom wrapper function that picks one or | |
209 | the other depending on which device was found. | |
210 | ||
211 | Note: On some architectures, the normal readl()/writel() functions | |
212 | traditionally assume that devices are the same endianness as the CPU, while | |
213 | using a hardware byte-reverse on the PCI bus when running a big-endian kernel. | |
214 | Drivers that use readl()/writel() this way are generally not portable, but | |
215 | tend to be limited to a particular SoC. | |
216 | ||
217 | hi_lo_readq(), lo_hi_readq(), hi_lo_readq_relaxed(), lo_hi_readq_relaxed(), | |
218 | ioread64_lo_hi(), ioread64_hi_lo(), ioread64be_lo_hi(), ioread64be_hi_lo(), | |
219 | hi_lo_writeq(), lo_hi_writeq(), hi_lo_writeq_relaxed(), lo_hi_writeq_relaxed(), | |
220 | iowrite64_lo_hi(), iowrite64_hi_lo(), iowrite64be_lo_hi(), iowrite64be_hi_lo() | |
221 | ||
222 | Some device drivers have 64-bit registers that cannot be accessed atomically | |
223 | on 32-bit architectures but allow two consecutive 32-bit accesses instead. | |
224 | Since it depends on the particular device which of the two halves has to be | |
225 | accessed first, a helper is provided for each combination of 64-bit accessors | |
226 | with either low/high or high/low word ordering. A device driver must include | |
227 | either <linux/io-64-nonatomic-lo-hi.h> or <linux/io-64-nonatomic-hi-lo.h> to | |
228 | get the function definitions along with helpers that redirect the normal | |
229 | readq()/writeq() to them on architectures that do not provide 64-bit access | |
230 | natively. | |
231 | ||
232 | __raw_readq(), __raw_readl(), __raw_readw(), __raw_readb(), | |
233 | __raw_writeq(), __raw_writel(), __raw_writew(), __raw_writeb() | |
234 | ||
235 | These are low-level MMIO accessors without barriers or byteorder changes and | |
236 | architecture specific behavior. Accesses are usually atomic in the sense that | |
237 | a four-byte __raw_readl() does not get split into individual byte loads, but | |
238 | multiple consecutive accesses can be combined on the bus. In portable code, it | |
239 | is only safe to use these to access memory behind a device bus but not MMIO | |
240 | registers, as there are no ordering guarantees with regard to other MMIO | |
241 | accesses or even spinlocks. The byte order is generally the same as for normal | |
242 | memory, so unlike the other functions, these can be used to copy data between | |
243 | kernel memory and device memory. | |
244 | ||
245 | inl(), inw(), inb(), outl(), outw(), outb() | |
246 | ||
247 | PCI I/O port resources traditionally require separate helpers as they are | |
248 | implemented using special instructions on the x86 architecture. On most other | |
249 | architectures, these are mapped to readl()/writel() style accessors | |
250 | internally, usually pointing to a fixed area in virtual memory. Instead of an | |
251 | ``__iomem`` pointer, the address is a 32-bit integer token to identify a port | |
252 | number. PCI requires I/O port access to be non-posted, meaning that an outb() | |
253 | must complete before the following code executes, while a normal writeb() may | |
254 | still be in progress. On architectures that correctly implement this, I/O port | |
255 | access is therefore ordered against spinlocks. Many non-x86 PCI host bridge | |
256 | implementations and CPU architectures however fail to implement non-posted I/O | |
257 | space on PCI, so they can end up being posted on such hardware. | |
258 | ||
259 | In some architectures, the I/O port number space has a 1:1 mapping to | |
260 | ``__iomem`` pointers, but this is not recommended and device drivers should | |
261 | not rely on that for portability. Similarly, an I/O port number as described | |
262 | in a PCI base address register may not correspond to the port number as seen | |
263 | by a device driver. Portable drivers need to read the port number for the | |
264 | resource provided by the kernel. | |
265 | ||
266 | There are no direct 64-bit I/O port accessors, but pci_iomap() in combination | |
267 | with ioread64/iowrite64 can be used instead. | |
268 | ||
269 | inl_p(), inw_p(), inb_p(), outl_p(), outw_p(), outb_p() | |
270 | ||
271 | On ISA devices that require specific timing, the _p versions of the I/O | |
272 | accessors add a small delay. On architectures that do not have ISA buses, | |
273 | these are aliases to the normal inb/outb helpers. | |
274 | ||
275 | readsq, readsl, readsw, readsb | |
276 | writesq, writesl, writesw, writesb | |
277 | ioread64_rep, ioread32_rep, ioread16_rep, ioread8_rep | |
278 | iowrite64_rep, iowrite32_rep, iowrite16_rep, iowrite8_rep | |
279 | insl, insw, insb, outsl, outsw, outsb | |
280 | ||
281 | These are helpers that access the same address multiple times, usually to copy | |
282 | data between kernel memory byte stream and a FIFO buffer. Unlike the normal | |
283 | MMIO accessors, these do not perform a byteswap on big-endian kernels, so the | |
284 | first byte in the FIFO register corresponds to the first byte in the memory | |
285 | buffer regardless of the architecture. | |
286 | ||
08e9b5be HM |
287 | Device memory mapping modes |
288 | =========================== | |
289 | ||
290 | Some architectures support multiple modes for mapping device memory. | |
291 | ioremap_*() variants provide a common abstraction around these | |
292 | architecture-specific modes, with a shared set of semantics. | |
293 | ||
294 | ioremap() is the most common mapping type, and is applicable to typical device | |
295 | memory (e.g. I/O registers). Other modes can offer weaker or stronger | |
296 | guarantees, if supported by the architecture. From most to least common, they | |
297 | are as follows: | |
298 | ||
299 | ioremap() | |
300 | --------- | |
301 | ||
302 | The default mode, suitable for most memory-mapped devices, e.g. control | |
303 | registers. Memory mapped using ioremap() has the following characteristics: | |
304 | ||
305 | * Uncached - CPU-side caches are bypassed, and all reads and writes are handled | |
306 | directly by the device | |
307 | * No speculative operations - the CPU may not issue a read or write to this | |
308 | memory, unless the instruction that does so has been reached in committed | |
309 | program flow. | |
310 | * No reordering - The CPU may not reorder accesses to this memory mapping with | |
311 | respect to each other. On some architectures, this relies on barriers in | |
312 | readl_relaxed()/writel_relaxed(). | |
313 | * No repetition - The CPU may not issue multiple reads or writes for a single | |
314 | program instruction. | |
315 | * No write-combining - Each I/O operation results in one discrete read or write | |
316 | being issued to the device, and multiple writes are not combined into larger | |
317 | writes. This may or may not be enforced when using __raw I/O accessors or | |
318 | pointer dereferences. | |
319 | * Non-executable - The CPU is not allowed to speculate instruction execution | |
320 | from this memory (it probably goes without saying, but you're also not | |
321 | allowed to jump into device memory). | |
322 | ||
323 | On many platforms and buses (e.g. PCI), writes issued through ioremap() | |
324 | mappings are posted, which means that the CPU does not wait for the write to | |
325 | actually reach the target device before retiring the write instruction. | |
326 | ||
327 | On many platforms, I/O accesses must be aligned with respect to the access | |
328 | size; failure to do so will result in an exception or unpredictable results. | |
329 | ||
330 | ioremap_wc() | |
331 | ------------ | |
332 | ||
333 | Maps I/O memory as normal memory with write combining. Unlike ioremap(), | |
334 | ||
335 | * The CPU may speculatively issue reads from the device that the program | |
336 | didn't actually execute, and may choose to basically read whatever it wants. | |
337 | * The CPU may reorder operations as long as the result is consistent from the | |
338 | program's point of view. | |
339 | * The CPU may write to the same location multiple times, even when the program | |
340 | issued a single write. | |
341 | * The CPU may combine several writes into a single larger write. | |
342 | ||
343 | This mode is typically used for video framebuffers, where it can increase | |
344 | performance of writes. It can also be used for other blocks of memory in | |
345 | devices (e.g. buffers or shared memory), but care must be taken as accesses are | |
346 | not guaranteed to be ordered with respect to normal ioremap() MMIO register | |
347 | accesses without explicit barriers. | |
348 | ||
349 | On a PCI bus, it is usually safe to use ioremap_wc() on MMIO areas marked as | |
350 | ``IORESOURCE_PREFETCH``, but it may not be used on those without the flag. | |
351 | For on-chip devices, there is no corresponding flag, but a driver can use | |
352 | ioremap_wc() on a device that is known to be safe. | |
353 | ||
354 | ioremap_wt() | |
355 | ------------ | |
356 | ||
357 | Maps I/O memory as normal memory with write-through caching. Like ioremap_wc(), | |
358 | but also, | |
359 | ||
360 | * The CPU may cache writes issued to and reads from the device, and serve reads | |
361 | from that cache. | |
362 | ||
363 | This mode is sometimes used for video framebuffers, where drivers still expect | |
364 | writes to reach the device in a timely manner (and not be stuck in the CPU | |
365 | cache), but reads may be served from the cache for efficiency. However, it is | |
366 | rarely useful these days, as framebuffer drivers usually perform writes only, | |
367 | for which ioremap_wc() is more efficient (as it doesn't needlessly trash the | |
368 | cache). Most drivers should not use this. | |
369 | ||
370 | ioremap_np() | |
371 | ------------ | |
372 | ||
373 | Like ioremap(), but explicitly requests non-posted write semantics. On some | |
374 | architectures and buses, ioremap() mappings have posted write semantics, which | |
375 | means that writes can appear to "complete" from the point of view of the | |
376 | CPU before the written data actually arrives at the target device. Writes are | |
377 | still ordered with respect to other writes and reads from the same device, but | |
378 | due to the posted write semantics, this is not the case with respect to other | |
379 | devices. ioremap_np() explicitly requests non-posted semantics, which means | |
380 | that the write instruction will not appear to complete until the device has | |
381 | received (and to some platform-specific extent acknowledged) the written data. | |
382 | ||
383 | This mapping mode primarily exists to cater for platforms with bus fabrics that | |
384 | require this particular mapping mode to work correctly. These platforms set the | |
385 | ``IORESOURCE_MEM_NONPOSTED`` flag for a resource that requires ioremap_np() | |
386 | semantics and portable drivers should use an abstraction that automatically | |
387 | selects it where appropriate (see the `Higher-level ioremap abstractions`_ | |
388 | section below). | |
389 | ||
390 | The bare ioremap_np() is only available on some architectures; on others, it | |
391 | always returns NULL. Drivers should not normally use it, unless they are | |
392 | platform-specific or they derive benefit from non-posted writes where | |
393 | supported, and can fall back to ioremap() otherwise. The normal approach to | |
394 | ensure posted write completion is to do a dummy read after a write as | |
395 | explained in `Accessing the device`_, which works with ioremap() on all | |
396 | platforms. | |
397 | ||
398 | ioremap_np() should never be used for PCI drivers. PCI memory space writes are | |
399 | always posted, even on architectures that otherwise implement ioremap_np(). | |
400 | Using ioremap_np() for PCI BARs will at best result in posted write semantics, | |
401 | and at worst result in complete breakage. | |
402 | ||
403 | Note that non-posted write semantics are orthogonal to CPU-side ordering | |
404 | guarantees. A CPU may still choose to issue other reads or writes before a | |
405 | non-posted write instruction retires. See the previous section on MMIO access | |
406 | functions for details on the CPU side of things. | |
407 | ||
408 | ioremap_uc() | |
409 | ------------ | |
410 | ||
411 | ioremap_uc() behaves like ioremap() except that on the x86 architecture without | |
412 | 'PAT' mode, it marks memory as uncached even when the MTRR has designated | |
ff61f079 | 413 | it as cacheable, see Documentation/arch/x86/pat.rst. |
08e9b5be HM |
414 | |
415 | Portable drivers should avoid the use of ioremap_uc(). | |
416 | ||
417 | ioremap_cache() | |
418 | --------------- | |
419 | ||
420 | ioremap_cache() effectively maps I/O memory as normal RAM. CPU write-back | |
421 | caches can be used, and the CPU is free to treat the device as if it were a | |
422 | block of RAM. This should never be used for device memory which has side | |
423 | effects of any kind, or which does not return the data previously written on | |
424 | read. | |
425 | ||
426 | It should also not be used for actual RAM, as the returned pointer is an | |
427 | ``__iomem`` token. memremap() can be used for mapping normal RAM that is outside | |
428 | of the linear kernel memory area to a regular pointer. | |
429 | ||
430 | Portable drivers should avoid the use of ioremap_cache(). | |
431 | ||
432 | Architecture example | |
433 | -------------------- | |
434 | ||
435 | Here is how the above modes map to memory attribute settings on the ARM64 | |
436 | architecture: | |
437 | ||
438 | +------------------------+--------------------------------------------+ | |
439 | | API | Memory region type and cacheability | | |
440 | +------------------------+--------------------------------------------+ | |
441 | | ioremap_np() | Device-nGnRnE | | |
442 | +------------------------+--------------------------------------------+ | |
443 | | ioremap() | Device-nGnRE | | |
444 | +------------------------+--------------------------------------------+ | |
445 | | ioremap_uc() | (not implemented) | | |
446 | +------------------------+--------------------------------------------+ | |
447 | | ioremap_wc() | Normal-Non Cacheable | | |
448 | +------------------------+--------------------------------------------+ | |
449 | | ioremap_wt() | (not implemented; fallback to ioremap) | | |
450 | +------------------------+--------------------------------------------+ | |
451 | | ioremap_cache() | Normal-Write-Back Cacheable | | |
452 | +------------------------+--------------------------------------------+ | |
453 | ||
454 | Higher-level ioremap abstractions | |
455 | ================================= | |
456 | ||
457 | Instead of using the above raw ioremap() modes, drivers are encouraged to use | |
458 | higher-level APIs. These APIs may implement platform-specific logic to | |
459 | automatically choose an appropriate ioremap mode on any given bus, allowing for | |
460 | a platform-agnostic driver to work on those platforms without any special | |
461 | cases. At the time of this writing, the following ioremap() wrappers have such | |
462 | logic: | |
463 | ||
464 | devm_ioremap_resource() | |
465 | ||
466 | Can automatically select ioremap_np() over ioremap() according to platform | |
467 | requirements, if the ``IORESOURCE_MEM_NONPOSTED`` flag is set on the struct | |
468 | resource. Uses devres to automatically unmap the resource when the driver | |
469 | probe() function fails or a device in unbound from its driver. | |
470 | ||
471 | Documented in Documentation/driver-api/driver-model/devres.rst. | |
472 | ||
473 | of_address_to_resource() | |
474 | ||
475 | Automatically sets the ``IORESOURCE_MEM_NONPOSTED`` flag for platforms that | |
476 | require non-posted writes for certain buses (see the nonposted-mmio and | |
477 | posted-mmio device tree properties). | |
478 | ||
479 | of_iomap() | |
480 | ||
481 | Maps the resource described in a ``reg`` property in the device tree, doing | |
482 | all required translations. Automatically selects ioremap_np() according to | |
483 | platform requirements, as above. | |
484 | ||
485 | pci_ioremap_bar(), pci_ioremap_wc_bar() | |
486 | ||
487 | Maps the resource described in a PCI base address without having to extract | |
488 | the physical address first. | |
489 | ||
490 | pci_iomap(), pci_iomap_wc() | |
491 | ||
492 | Like pci_ioremap_bar()/pci_ioremap_bar(), but also works on I/O space when | |
493 | used together with ioread32()/iowrite32() and similar accessors | |
494 | ||
495 | pcim_iomap() | |
496 | ||
497 | Like pci_iomap(), but uses devres to automatically unmap the resource when | |
498 | the driver probe() function fails or a device in unbound from its driver | |
499 | ||
500 | Documented in Documentation/driver-api/driver-model/devres.rst. | |
501 | ||
502 | Not using these wrappers may make drivers unusable on certain platforms with | |
503 | stricter rules for mapping I/O memory. | |
504 | ||
7938f421 LDM |
505 | Generalizing Access to System and I/O Memory |
506 | ============================================ | |
507 | ||
508 | .. kernel-doc:: include/linux/iosys-map.h | |
509 | :doc: overview | |
510 | ||
511 | .. kernel-doc:: include/linux/iosys-map.h | |
512 | :internal: | |
513 | ||
8a8a602f JC |
514 | Public Functions Provided |
515 | ========================= | |
516 | ||
517 | .. kernel-doc:: arch/x86/include/asm/io.h | |
518 | :internal: | |
519 | ||
520 | .. kernel-doc:: lib/pci_iomap.c | |
521 | :export: |