Lines Matching +full:on +full:- +full:device
10 Bus-Independent Device Accesses
20 and devices, allowing device drivers to be written independently of bus
26 Getting Access to the Device
27 ----------------------------
31 memory, but as accesses to a device. Some architectures define devices
40 the device will be returned to you.
42 After you've finished using the device (say, in your module's exit
48 Accessing the device
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
65 provided. Do not use memset or memcpy on IO addresses; they are not
75 sit on may themselves have asynchronicity. In particular many authors
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
94 reg = ha->iobase;
96 WRT_REG_WORD(®->ictrl, 0);
99 * has been received by the device before we return from this
102 RD_REG_WORD(®->ictrl);
103 ha->flags.ints_enabled = 0;
111 performed by the device. The driver can use readb_relaxed() for
114 performance benefits on platforms that support it. The qla2xxx driver
117 calls, since only a few will indicate or depend on DMA completion.
123 --------------------
134 --------------------
137 allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and
153 ``void __iomem *reg``. On most architectures it is a regular pointer that
156 operated on an ``__iomem`` token, in particular the ioremap() and
160 While on most architectures, ioremap() creates a page table entry for an
173 little-endian PCI devices and on-chip peripherals. Portable device drivers
177 Documentation/driver-api/io_ordering.rst.
182 On architectures that require an expensive barrier for serializing against
184 each other, but contain a less expensive barrier operation. A device driver
189 See memory-barriers.txt for a more detailed discussion on the precise ordering
190 guarantees of the non-relaxed and relaxed versions.
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
199 overhead for an indirect function call implemented in lib/iomap.c, while on
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
209 the other depending on which device was found.
211 Note: On some architectures, the normal readl()/writel() functions
213 using a hardware byte-reverse on the PCI bus when running a big-endian kernel.
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
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
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
243 kernel memory and device memory.
248 implemented using special instructions on the x86 architecture. On most other
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()
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.
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
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
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,
283 MMIO accessors, these do not perform a byteswap on big-endian kernels, so the
287 Device memory mapping modes
290 Some architectures support multiple modes for mapping device 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
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
306 directly by the device
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()
325 actually reach the target device before retiring the write instruction.
327 On many platforms, I/O accesses must be aligned with respect to the access
331 ------------
335 * The CPU may speculatively issue reads from the device that the program
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.
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
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
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.
387 selects it where appropriate (see the `Higher-level ioremap abstractions`_
390 The bare ioremap_np() is only available on some architectures; on others, it
392 platform-specific or they derive benefit from non-posted writes where
395 explained in `Accessing the device`_, which works with ioremap() on all
399 always posted, even on architectures that otherwise implement ioremap_np().
403 Note that non-posted write semantics are orthogonal to CPU-side ordering
405 non-posted write instruction retires. See the previous section on MMIO access
406 functions for details on the CPU side of things.
409 ------------
411 ioremap_uc() is only meaningful on old x86-32 systems with the PAT extension,
412 and on ia64 with its slightly unconventional ioremap() behavior, everywhere
419 ---------------
421 ioremap_cache() effectively maps I/O memory as normal RAM. CPU write-back
422 caches can be used, and the CPU is free to treat the device as if it were a
423 block of RAM. This should never be used for device memory which has side
424 effects of any kind, or which does not return the data previously written on
434 --------------------
436 Here is how the above modes map to memory attribute settings on the ARM64
439 +------------------------+--------------------------------------------+
441 +------------------------+--------------------------------------------+
442 | ioremap_np() | Device-nGnRnE |
443 +------------------------+--------------------------------------------+
444 | ioremap() | Device-nGnRE |
445 +------------------------+--------------------------------------------+
447 +------------------------+--------------------------------------------+
448 | ioremap_wc() | Normal-Non Cacheable |
449 +------------------------+--------------------------------------------+
451 +------------------------+--------------------------------------------+
452 | ioremap_cache() | Normal-Write-Back Cacheable |
453 +------------------------+--------------------------------------------+
455 Higher-level ioremap abstractions
459 higher-level APIs. These APIs may implement platform-specific logic to
460 automatically choose an appropriate ioremap mode on any given bus, allowing for
461 a platform-agnostic driver to work on those platforms without any special
468 requirements, if the ``IORESOURCE_MEM_NONPOSTED`` flag is set on the struct
470 probe() function fails or a device in unbound from its driver.
472 Documented in Documentation/driver-api/driver-model/devres.rst.
477 require non-posted writes for certain buses (see the nonposted-mmio and
478 posted-mmio device tree properties).
482 Maps the resource described in a ``reg`` property in the device tree, doing
493 Like pci_ioremap_bar()/pci_ioremap_bar(), but also works on I/O space when
499 the driver probe() function fails or a device in unbound from its driver
501 Documented in Documentation/driver-api/driver-model/devres.rst.
503 Not using these wrappers may make drivers unusable on certain platforms with
509 .. kernel-doc:: include/linux/iosys-map.h
512 .. kernel-doc:: include/linux/iosys-map.h
518 .. kernel-doc:: arch/x86/include/asm/io.h