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 | |
39 | should call :c:func:`ioremap()`. An address suitable for accessing | |
40 | the device will be returned to you. | |
41 | ||
42 | After you've finished using the device (say, in your module's exit | |
43 | routine), call :c:func:`iounmap()` in order to return the address | |
44 | space to the kernel. Most architectures allocate new address space each | |
45 | time you call :c:func:`ioremap()`, and they can run out unless you | |
46 | call :c:func:`iounmap()`. | |
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 | |
63 | 8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, | |
64 | :c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are | |
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 | |
138 | long. These functions are :c:func:`inb()`, :c:func:`inw()`, | |
139 | :c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and | |
140 | :c:func:`outl()`. | |
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. | |
145 | There are also equivalents to memcpy. The :c:func:`ins()` and | |
146 | :c:func:`outs()` functions copy bytes, words or longs to the given | |
147 | port. | |
148 | ||
149 | Public Functions Provided | |
150 | ========================= | |
151 | ||
152 | .. kernel-doc:: arch/x86/include/asm/io.h | |
153 | :internal: | |
154 | ||
155 | .. kernel-doc:: lib/pci_iomap.c | |
156 | :export: |