docs: Convert the deviceio template to RST

-323

Documentation/DocBook/deviceiobook.tmpl

··· 1 - <?xml version="1.0" encoding="UTF-8"?> 2 - <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 - 5 - <book id="DoingIO"> 6 - <bookinfo> 7 - <title>Bus-Independent Device Accesses</title> 8 - 9 - <authorgroup> 10 - <author> 11 - <firstname>Matthew</firstname> 12 - <surname>Wilcox</surname> 13 - <affiliation> 14 - <address> 15 - <email>matthew@wil.cx</email> 16 - </address> 17 - </affiliation> 18 - </author> 19 - </authorgroup> 20 - 21 - <authorgroup> 22 - <author> 23 - <firstname>Alan</firstname> 24 - <surname>Cox</surname> 25 - <affiliation> 26 - <address> 27 - <email>alan@lxorguk.ukuu.org.uk</email> 28 - </address> 29 - </affiliation> 30 - </author> 31 - </authorgroup> 32 - 33 - <copyright> 34 - <year>2001</year> 35 - <holder>Matthew Wilcox</holder> 36 - </copyright> 37 - 38 - <legalnotice> 39 - <para> 40 - This documentation is free software; you can redistribute 41 - it and/or modify it under the terms of the GNU General Public 42 - License as published by the Free Software Foundation; either 43 - version 2 of the License, or (at your option) any later 44 - version. 45 - </para> 46 - 47 - <para> 48 - This program is distributed in the hope that it will be 49 - useful, but WITHOUT ANY WARRANTY; without even the implied 50 - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 51 - See the GNU General Public License for more details. 52 - </para> 53 - 54 - <para> 55 - You should have received a copy of the GNU General Public 56 - License along with this program; if not, write to the Free 57 - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 58 - MA 02111-1307 USA 59 - </para> 60 - 61 - <para> 62 - For more details see the file COPYING in the source 63 - distribution of Linux. 64 - </para> 65 - </legalnotice> 66 - </bookinfo> 67 - 68 - <toc></toc> 69 - 70 - <chapter id="intro"> 71 - <title>Introduction</title> 72 - <para> 73 - Linux provides an API which abstracts performing IO across all busses 74 - and devices, allowing device drivers to be written independently of 75 - bus type. 76 - </para> 77 - </chapter> 78 - 79 - <chapter id="bugs"> 80 - <title>Known Bugs And Assumptions</title> 81 - <para> 82 - None. 83 - </para> 84 - </chapter> 85 - 86 - <chapter id="mmio"> 87 - <title>Memory Mapped IO</title> 88 - <sect1 id="getting_access_to_the_device"> 89 - <title>Getting Access to the Device</title> 90 - <para> 91 - The most widely supported form of IO is memory mapped IO. 92 - That is, a part of the CPU's address space is interpreted 93 - not as accesses to memory, but as accesses to a device. Some 94 - architectures define devices to be at a fixed address, but most 95 - have some method of discovering devices. The PCI bus walk is a 96 - good example of such a scheme. This document does not cover how 97 - to receive such an address, but assumes you are starting with one. 98 - Physical addresses are of type unsigned long. 99 - </para> 100 - 101 - <para> 102 - This address should not be used directly. Instead, to get an 103 - address suitable for passing to the accessor functions described 104 - below, you should call <function>ioremap</function>. 105 - An address suitable for accessing the device will be returned to you. 106 - </para> 107 - 108 - <para> 109 - After you've finished using the device (say, in your module's 110 - exit routine), call <function>iounmap</function> in order to return 111 - the address space to the kernel. Most architectures allocate new 112 - address space each time you call <function>ioremap</function>, and 113 - they can run out unless you call <function>iounmap</function>. 114 - </para> 115 - </sect1> 116 - 117 - <sect1 id="accessing_the_device"> 118 - <title>Accessing the device</title> 119 - <para> 120 - The part of the interface most used by drivers is reading and 121 - writing memory-mapped registers on the device. Linux provides 122 - interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit 123 - quantities. Due to a historical accident, these are named byte, 124 - word, long and quad accesses. Both read and write accesses are 125 - supported; there is no prefetch support at this time. 126 - </para> 127 - 128 - <para> 129 - The functions are named <function>readb</function>, 130 - <function>readw</function>, <function>readl</function>, 131 - <function>readq</function>, <function>readb_relaxed</function>, 132 - <function>readw_relaxed</function>, <function>readl_relaxed</function>, 133 - <function>readq_relaxed</function>, <function>writeb</function>, 134 - <function>writew</function>, <function>writel</function> and 135 - <function>writeq</function>. 136 - </para> 137 - 138 - <para> 139 - Some devices (such as framebuffers) would like to use larger 140 - transfers than 8 bytes at a time. For these devices, the 141 - <function>memcpy_toio</function>, <function>memcpy_fromio</function> 142 - and <function>memset_io</function> functions are provided. 143 - Do not use memset or memcpy on IO addresses; they 144 - are not guaranteed to copy data in order. 145 - </para> 146 - 147 - <para> 148 - The read and write functions are defined to be ordered. That is the 149 - compiler is not permitted to reorder the I/O sequence. When the 150 - ordering can be compiler optimised, you can use <function> 151 - __readb</function> and friends to indicate the relaxed ordering. Use 152 - this with care. 153 - </para> 154 - 155 - <para> 156 - While the basic functions are defined to be synchronous with respect 157 - to each other and ordered with respect to each other the busses the 158 - devices sit on may themselves have asynchronicity. In particular many 159 - authors are burned by the fact that PCI bus writes are posted 160 - asynchronously. A driver author must issue a read from the same 161 - device to ensure that writes have occurred in the specific cases the 162 - author cares. This kind of property cannot be hidden from driver 163 - writers in the API. In some cases, the read used to flush the device 164 - may be expected to fail (if the card is resetting, for example). In 165 - that case, the read should be done from config space, which is 166 - guaranteed to soft-fail if the card doesn't respond. 167 - </para> 168 - 169 - <para> 170 - The following is an example of flushing a write to a device when 171 - the driver would like to ensure the write's effects are visible prior 172 - to continuing execution. 173 - </para> 174 - 175 - <programlisting> 176 - static inline void 177 - qla1280_disable_intrs(struct scsi_qla_host *ha) 178 - { 179 - struct device_reg *reg; 180 - 181 - reg = ha->iobase; 182 - /* disable risc and host interrupts */ 183 - WRT_REG_WORD(&reg->ictrl, 0); 184 - /* 185 - * The following read will ensure that the above write 186 - * has been received by the device before we return from this 187 - * function. 188 - */ 189 - RD_REG_WORD(&reg->ictrl); 190 - ha->flags.ints_enabled = 0; 191 - } 192 - </programlisting> 193 - 194 - <para> 195 - In addition to write posting, on some large multiprocessing systems 196 - (e.g. SGI Challenge, Origin and Altix machines) posted writes won't 197 - be strongly ordered coming from different CPUs. Thus it's important 198 - to properly protect parts of your driver that do memory-mapped writes 199 - with locks and use the <function>mmiowb</function> to make sure they 200 - arrive in the order intended. Issuing a regular <function>readX 201 - </function> will also ensure write ordering, but should only be used 202 - when the driver has to be sure that the write has actually arrived 203 - at the device (not that it's simply ordered with respect to other 204 - writes), since a full <function>readX</function> is a relatively 205 - expensive operation. 206 - </para> 207 - 208 - <para> 209 - Generally, one should use <function>mmiowb</function> prior to 210 - releasing a spinlock that protects regions using <function>writeb 211 - </function> or similar functions that aren't surrounded by <function> 212 - readb</function> calls, which will ensure ordering and flushing. The 213 - following pseudocode illustrates what might occur if write ordering 214 - isn't guaranteed via <function>mmiowb</function> or one of the 215 - <function>readX</function> functions. 216 - </para> 217 - 218 - <programlisting> 219 - CPU A: spin_lock_irqsave(&dev_lock, flags) 220 - CPU A: ... 221 - CPU A: writel(newval, ring_ptr); 222 - CPU A: spin_unlock_irqrestore(&dev_lock, flags) 223 - ... 224 - CPU B: spin_lock_irqsave(&dev_lock, flags) 225 - CPU B: writel(newval2, ring_ptr); 226 - CPU B: ... 227 - CPU B: spin_unlock_irqrestore(&dev_lock, flags) 228 - </programlisting> 229 - 230 - <para> 231 - In the case above, newval2 could be written to ring_ptr before 232 - newval. Fixing it is easy though: 233 - </para> 234 - 235 - <programlisting> 236 - CPU A: spin_lock_irqsave(&dev_lock, flags) 237 - CPU A: ... 238 - CPU A: writel(newval, ring_ptr); 239 - CPU A: mmiowb(); /* ensure no other writes beat us to the device */ 240 - CPU A: spin_unlock_irqrestore(&dev_lock, flags) 241 - ... 242 - CPU B: spin_lock_irqsave(&dev_lock, flags) 243 - CPU B: writel(newval2, ring_ptr); 244 - CPU B: ... 245 - CPU B: mmiowb(); 246 - CPU B: spin_unlock_irqrestore(&dev_lock, flags) 247 - </programlisting> 248 - 249 - <para> 250 - See tg3.c for a real world example of how to use <function>mmiowb 251 - </function> 252 - </para> 253 - 254 - <para> 255 - PCI ordering rules also guarantee that PIO read responses arrive 256 - after any outstanding DMA writes from that bus, since for some devices 257 - the result of a <function>readb</function> call may signal to the 258 - driver that a DMA transaction is complete. In many cases, however, 259 - the driver may want to indicate that the next 260 - <function>readb</function> call has no relation to any previous DMA 261 - writes performed by the device. The driver can use 262 - <function>readb_relaxed</function> for these cases, although only 263 - some platforms will honor the relaxed semantics. Using the relaxed 264 - read functions will provide significant performance benefits on 265 - platforms that support it. The qla2xxx driver provides examples 266 - of how to use <function>readX_relaxed</function>. In many cases, 267 - a majority of the driver's <function>readX</function> calls can 268 - safely be converted to <function>readX_relaxed</function> calls, since 269 - only a few will indicate or depend on DMA completion. 270 - </para> 271 - </sect1> 272 - 273 - </chapter> 274 - 275 - <chapter id="port_space_accesses"> 276 - <title>Port Space Accesses</title> 277 - <sect1 id="port_space_explained"> 278 - <title>Port Space Explained</title> 279 - 280 - <para> 281 - Another form of IO commonly supported is Port Space. This is a 282 - range of addresses separate to the normal memory address space. 283 - Access to these addresses is generally not as fast as accesses 284 - to the memory mapped addresses, and it also has a potentially 285 - smaller address space. 286 - </para> 287 - 288 - <para> 289 - Unlike memory mapped IO, no preparation is required 290 - to access port space. 291 - </para> 292 - 293 - </sect1> 294 - <sect1 id="accessing_port_space"> 295 - <title>Accessing Port Space</title> 296 - <para> 297 - Accesses to this space are provided through a set of functions 298 - which allow 8-bit, 16-bit and 32-bit accesses; also 299 - known as byte, word and long. These functions are 300 - <function>inb</function>, <function>inw</function>, 301 - <function>inl</function>, <function>outb</function>, 302 - <function>outw</function> and <function>outl</function>. 303 - </para> 304 - 305 - <para> 306 - Some variants are provided for these functions. Some devices 307 - require that accesses to their ports are slowed down. This 308 - functionality is provided by appending a <function>_p</function> 309 - to the end of the function. There are also equivalents to memcpy. 310 - The <function>ins</function> and <function>outs</function> 311 - functions copy bytes, words or longs to the given port. 312 - </para> 313 - </sect1> 314 - 315 - </chapter> 316 - 317 - <chapter id="pubfunctions"> 318 - <title>Public Functions Provided</title> 319 - !Iarch/x86/include/asm/io.h 320 - !Elib/pci_iomap.c 321 - </chapter> 322 - 323 - </book>

+201

Documentation/driver-api/device-io.rst

··· 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(&reg->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(&reg->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:

+1

Documentation/driver-api/index.rst

··· 16 16 17 17 basics 18 18 infrastructure 19 + device-io 19 20 dma-buf 20 21 device_link 21 22 message-based