Lines Matching +full:cpu +full:- +full:to +full:- +full:pci
10 Bus-Independent Device Accesses
20 and devices, allowing device drivers to be written independently of bus
26 Getting Access to the Device
27 ----------------------------
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
37 This address should not be used directly. Instead, to get an address
38 suitable for passing to the accessor functions described below, you
40 the device will be returned to you.
43 routine), call iounmap() in order to return the address
44 space to the kernel. Most architectures allocate new address space each
49 --------------------
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
62 Some devices (such as framebuffers) would like to use larger transfers than
66 guaranteed to copy data in order.
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
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
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
80 cases, the read used to flush the device may be expected to fail (if the
82 from config space, which is guaranteed to soft-fail if the card doesn't
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
94 reg = ha->iobase;
96 WRT_REG_WORD(®->ictrl, 0);
102 RD_REG_WORD(®->ictrl);
103 ha->flags.ints_enabled = 0;
106 PCI ordering rules also guarantee that PIO read responses arrive after any
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
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()
123 --------------------
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
130 Unlike memory mapped IO, no preparation is required to access port
134 --------------------
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
143 that accesses to their ports are slowed down. This functionality is
144 provided by appending a ``_p`` to the end of the function.
145 There are also equivalents to memcpy. The ins() and
146 outs() functions copy bytes, words or longs to the given
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
157 readl()/writel() functions. The 'sparse' semantic code checker can be used to
161 uncached virtual address pointing to the physical MMIO address, some
173 little-endian PCI devices and on-chip peripherals. Portable device drivers
174 should generally use these for any access to ``__iomem`` pointers.
177 Documentation/driver-api/io_ordering.rst.
189 See memory-barriers.txt for a more detailed discussion on the precise ordering
190 guarantees of the non-relaxed and relaxed versions.
195 These are an alternative to the normal readl()/writel() functions, with almost
197 for mapping PCI I/O space with pci_iomap() or ioport_map(). On architectures
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
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.
215 tend to be limited to a particular SoC.
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
227 either <linux/io-64-nonatomic-lo-hi.h> or <linux/io-64-nonatomic-hi-lo.h> to
229 readq()/writeq() to them on architectures that do not provide 64-bit access
235 These are low-level MMIO accessors without barriers or byteorder changes and
237 a four-byte __raw_readl() does not get split into individual byte loads, but
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
242 memory, so unlike the other functions, these can be used to copy data between
247 PCI I/O port resources traditionally require separate helpers as they are
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()
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.
259 In some architectures, the I/O port number space has a 1:1 mapping to
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
266 There are no direct 64-bit I/O port accessors, but pci_iomap() in combination
273 these are aliases to the normal inb/outb helpers.
281 These are helpers that access the same address multiple times, usually to copy
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
292 architecture-specific modes, with a shared set of semantics.
294 ioremap() is the most common mapping type, and is applicable to typical device
296 guarantees, if supported by the architecture. From most to least common, they
300 ---------
302 The default mode, suitable for most memory-mapped devices, e.g. control
305 * Uncached - CPU-side caches are bypassed, and all reads and writes are handled
307 * No speculative operations - the CPU may not issue a read or write to this
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
313 * No repetition - The CPU may not issue multiple reads or writes for a single
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
319 * Non-executable - The CPU is not allowed to speculate instruction execution
321 allowed to jump into device memory).
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
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.
331 ------------
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
339 * The CPU may write to the same location multiple times, even when the program
341 * The CPU may combine several writes into a single larger write.
346 not guaranteed to be ordered with respect to normal ioremap() MMIO register
349 On a PCI bus, it is usually safe to use ioremap_wc() on MMIO areas marked as
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.
355 ------------
357 Maps I/O memory as normal memory with write-through caching. Like ioremap_wc(),
360 * The CPU may cache writes issued to and reads from the device, and serve reads
364 writes to reach the device in a timely manner (and not be stuck in the CPU
371 ------------
373 Like ioremap(), but explicitly requests non-posted write semantics. On some
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.
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
387 selects it where appropriate (see the `Higher-level ioremap abstractions`_
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
398 ioremap_np() should never be used for PCI drivers. PCI memory space writes are
400 Using ioremap_np() for PCI BARs will at best result in posted write semantics,
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.
409 ------------
418 ---------------
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
428 of the linear kernel memory area to a regular pointer.
433 --------------------
435 Here is how the above modes map to memory attribute settings on the ARM64
438 +------------------------+--------------------------------------------+
440 +------------------------+--------------------------------------------+
441 | ioremap_np() | Device-nGnRnE |
442 +------------------------+--------------------------------------------+
443 | ioremap() | Device-nGnRE |
444 +------------------------+--------------------------------------------+
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 +------------------------+--------------------------------------------+
454 Higher-level ioremap abstractions
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
460 a platform-agnostic driver to work on those platforms without any special
466 Can automatically select ioremap_np() over ioremap() according to platform
468 resource. Uses devres to automatically unmap the resource when the driver
471 Documented in Documentation/driver-api/driver-model/devres.rst.
476 require non-posted writes for certain buses (see the nonposted-mmio and
477 posted-mmio device tree properties).
482 all required translations. Automatically selects ioremap_np() according to
487 Maps the resource described in a PCI base address without having to extract
497 Like pci_iomap(), but uses devres to automatically unmap the resource when
500 Documented in Documentation/driver-api/driver-model/devres.rst.
505 Generalizing Access to System and I/O Memory
508 .. kernel-doc:: include/linux/iosys-map.h
511 .. kernel-doc:: include/linux/iosys-map.h
517 .. kernel-doc:: arch/x86/include/asm/io.h
520 .. kernel-doc:: lib/pci_iomap.c