^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. Copyright 2001 Matthew Wilcox
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. This documentation is free software; you can redistribute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. it and/or modify it under the terms of the GNU General Public
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) .. License as published by the Free Software Foundation; either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) .. version 2 of the License, or (at your option) any later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) .. version.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Bus-Independent Device Accesses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :Author: Matthew Wilcox
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) :Author: Alan Cox
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Linux provides an API which abstracts performing IO across all busses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) and devices, allowing device drivers to be written independently of bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Memory Mapped IO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Getting Access to the Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) The most widely supported form of IO is memory mapped IO. That is, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) part of the CPU's address space is interpreted not as accesses to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) memory, but as accesses to a device. Some architectures define devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) to be at a fixed address, but most have some method of discovering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) devices. The PCI bus walk is a good example of such a scheme. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) document does not cover how to receive such an address, but assumes you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) are starting with one. Physical addresses are of type unsigned long.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) This address should not be used directly. Instead, to get an address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) suitable for passing to the accessor functions described below, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) should call ioremap(). An address suitable for accessing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) the device will be returned to you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) After you've finished using the device (say, in your module's exit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) routine), call iounmap() in order to return the address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) space to the kernel. Most architectures allocate new address space each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) time you call ioremap(), and they can run out unless you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) call iounmap().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Accessing the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) The part of the interface most used by drivers is reading and writing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) memory-mapped registers on the device. Linux provides interfaces to read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) and write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) historical accident, these are named byte, word, long and quad accesses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Both read and write accesses are supported; there is no prefetch support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) at this time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) The functions are named readb(), readw(), readl(), readq(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) writeb(), writew(), writel() and writeq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Some devices (such as framebuffers) would like to use larger transfers than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 8 bytes at a time. For these devices, the memcpy_toio(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) memcpy_fromio() and memset_io() functions are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) provided. Do not use memset or memcpy on IO addresses; they are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) guaranteed to copy data in order.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) The read and write functions are defined to be ordered. That is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) compiler is not permitted to reorder the I/O sequence. When the ordering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) can be compiler optimised, you can use __readb() and friends to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) indicate the relaxed ordering. Use this with care.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) While the basic functions are defined to be synchronous with respect to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) each other and ordered with respect to each other the busses the devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) sit on may themselves have asynchronicity. In particular many authors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) are burned by the fact that PCI bus writes are posted asynchronously. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) driver author must issue a read from the same device to ensure that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) writes have occurred in the specific cases the author cares. This kind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) of property cannot be hidden from driver writers in the API. In some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) cases, the read used to flush the device may be expected to fail (if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) card is resetting, for example). In that case, the read should be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) from config space, which is guaranteed to soft-fail if the card doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) respond.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) The following is an example of flushing a write to a device when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) driver would like to ensure the write's effects are visible prior to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) continuing execution::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) static inline void
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) qla1280_disable_intrs(struct scsi_qla_host *ha)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) struct device_reg *reg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) reg = ha->iobase;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) /* disable risc and host interrupts */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) WRT_REG_WORD(®->ictrl, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) * The following read will ensure that the above write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) * has been received by the device before we return from this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) * function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) RD_REG_WORD(®->ictrl);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ha->flags.ints_enabled = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) PCI ordering rules also guarantee that PIO read responses arrive after any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) outstanding DMA writes from that bus, since for some devices the result of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) a readb() call may signal to the driver that a DMA transaction is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) complete. In many cases, however, the driver may want to indicate that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) next readb() call has no relation to any previous DMA writes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) performed by the device. The driver can use readb_relaxed() for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) these cases, although only some platforms will honor the relaxed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) semantics. Using the relaxed read functions will provide significant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) performance benefits on platforms that support it. The qla2xxx driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) provides examples of how to use readX_relaxed(). In many cases, a majority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) of the driver's readX() calls can safely be converted to readX_relaxed()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) calls, since only a few will indicate or depend on DMA completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Port Space Accesses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Port Space Explained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) Another form of IO commonly supported is Port Space. This is a range of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) addresses separate to the normal memory address space. Access to these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) addresses is generally not as fast as accesses to the memory mapped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) addresses, and it also has a potentially smaller address space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Unlike memory mapped IO, no preparation is required to access port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Accessing Port Space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Accesses to this space are provided through a set of functions which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) long. These functions are inb(), inw(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) inl(), outb(), outw() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) outl().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Some variants are provided for these functions. Some devices require
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) that accesses to their ports are slowed down. This functionality is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) provided by appending a ``_p`` to the end of the function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) There are also equivalents to memcpy. The ins() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) outs() functions copy bytes, words or longs to the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) port.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Public Functions Provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) .. kernel-doc:: arch/x86/include/asm/io.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) .. kernel-doc:: lib/pci_iomap.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) :export:
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags