]>
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 | ||
106 | In addition to write posting, on some large multiprocessing systems | |
107 | (e.g. SGI Challenge, Origin and Altix machines) posted writes won't be | |
108 | strongly ordered coming from different CPUs. Thus it's important to | |
109 | properly protect parts of your driver that do memory-mapped writes with | |
110 | locks and use the :c:func:`mmiowb()` to make sure they arrive in the | |
111 | order intended. Issuing a regular readX() will also ensure write ordering, | |
112 | but should only be used when the | |
113 | driver has to be sure that the write has actually arrived at the device | |
114 | (not that it's simply ordered with respect to other writes), since a | |
115 | full readX() is a relatively expensive operation. | |
116 | ||
117 | Generally, one should use :c:func:`mmiowb()` prior to releasing a spinlock | |
118 | that protects regions using :c:func:`writeb()` or similar functions that | |
119 | aren't surrounded by readb() calls, which will ensure ordering | |
120 | and flushing. The following pseudocode illustrates what might occur if | |
121 | write ordering isn't guaranteed via :c:func:`mmiowb()` or one of the | |
122 | readX() functions:: | |
123 | ||
124 | CPU A: spin_lock_irqsave(&dev_lock, flags) | |
125 | CPU A: ... | |
126 | CPU A: writel(newval, ring_ptr); | |
127 | CPU A: spin_unlock_irqrestore(&dev_lock, flags) | |
128 | ... | |
129 | CPU B: spin_lock_irqsave(&dev_lock, flags) | |
130 | CPU B: writel(newval2, ring_ptr); | |
131 | CPU B: ... | |
132 | CPU B: spin_unlock_irqrestore(&dev_lock, flags) | |
133 | ||
134 | In the case above, newval2 could be written to ring_ptr before newval. | |
135 | Fixing it is easy though:: | |
136 | ||
137 | CPU A: spin_lock_irqsave(&dev_lock, flags) | |
138 | CPU A: ... | |
139 | CPU A: writel(newval, ring_ptr); | |
140 | CPU A: mmiowb(); /* ensure no other writes beat us to the device */ | |
141 | CPU A: spin_unlock_irqrestore(&dev_lock, flags) | |
142 | ... | |
143 | CPU B: spin_lock_irqsave(&dev_lock, flags) | |
144 | CPU B: writel(newval2, ring_ptr); | |
145 | CPU B: ... | |
146 | CPU B: mmiowb(); | |
147 | CPU B: spin_unlock_irqrestore(&dev_lock, flags) | |
148 | ||
149 | See tg3.c for a real world example of how to use :c:func:`mmiowb()` | |
150 | ||
151 | PCI ordering rules also guarantee that PIO read responses arrive after any | |
152 | outstanding DMA writes from that bus, since for some devices the result of | |
153 | a readb() call may signal to the driver that a DMA transaction is | |
154 | complete. In many cases, however, the driver may want to indicate that the | |
155 | next readb() call has no relation to any previous DMA writes | |
156 | performed by the device. The driver can use readb_relaxed() for | |
157 | these cases, although only some platforms will honor the relaxed | |
158 | semantics. Using the relaxed read functions will provide significant | |
159 | performance benefits on platforms that support it. The qla2xxx driver | |
160 | provides examples of how to use readX_relaxed(). In many cases, a majority | |
161 | of the driver's readX() calls can safely be converted to readX_relaxed() | |
162 | calls, since only a few will indicate or depend on DMA completion. | |
163 | ||
164 | Port Space Accesses | |
165 | =================== | |
166 | ||
167 | Port Space Explained | |
168 | -------------------- | |
169 | ||
170 | Another form of IO commonly supported is Port Space. This is a range of | |
171 | addresses separate to the normal memory address space. Access to these | |
172 | addresses is generally not as fast as accesses to the memory mapped | |
173 | addresses, and it also has a potentially smaller address space. | |
174 | ||
175 | Unlike memory mapped IO, no preparation is required to access port | |
176 | space. | |
177 | ||
178 | Accessing Port Space | |
179 | -------------------- | |
180 | ||
181 | Accesses to this space are provided through a set of functions which | |
182 | allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and | |
183 | long. These functions are :c:func:`inb()`, :c:func:`inw()`, | |
184 | :c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and | |
185 | :c:func:`outl()`. | |
186 | ||
187 | Some variants are provided for these functions. Some devices require | |
188 | that accesses to their ports are slowed down. This functionality is | |
189 | provided by appending a ``_p`` to the end of the function. | |
190 | There are also equivalents to memcpy. The :c:func:`ins()` and | |
191 | :c:func:`outs()` functions copy bytes, words or longs to the given | |
192 | port. | |
193 | ||
194 | Public Functions Provided | |
195 | ========================= | |
196 | ||
197 | .. kernel-doc:: arch/x86/include/asm/io.h | |
198 | :internal: | |
199 | ||
200 | .. kernel-doc:: lib/pci_iomap.c | |
201 | :export: |