1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
2
3<book id="DoingIO">
4 <bookinfo>
5  <title>Bus-Independent Device Accesses</title>
6
7  <authorgroup>
8   <author>
9    <firstname>Matthew</firstname>
10    <surname>Wilcox</surname>
11    <affiliation>
12     <address>
13      <email>matthew@wil.cx</email>
14     </address>
15    </affiliation>
16   </author>
17  </authorgroup>
18
19  <authorgroup>
20   <author>
21    <firstname>Alan</firstname>
22    <surname>Cox</surname>
23    <affiliation>
24     <address>
25      <email>alan@redhat.com</email>
26     </address>
27    </affiliation>
28   </author>
29  </authorgroup>
30
31  <copyright>
32   <year>2001</year>
33   <holder>Matthew Wilcox</holder>
34  </copyright>
35
36  <legalnotice>
37   <para>
38     This documentation is free software; you can redistribute
39     it and/or modify it under the terms of the GNU General Public
40     License as published by the Free Software Foundation; either
41     version 2 of the License, or (at your option) any later
42     version.
43   </para>
44
45   <para>
46     This program is distributed in the hope that it will be
47     useful, but WITHOUT ANY WARRANTY; without even the implied
48     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
49     See the GNU General Public License for more details.
50   </para>
51
52   <para>
53     You should have received a copy of the GNU General Public
54     License along with this program; if not, write to the Free
55     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
56     MA 02111-1307 USA
57   </para>
58
59   <para>
60     For more details see the file COPYING in the source
61     distribution of Linux.
62   </para>
63  </legalnotice>
64 </bookinfo>
65
66<toc></toc>
67
68  <chapter id="intro">
69      <title>Introduction</title>
70  <para>
71	Linux provides an API which abstracts performing IO across all busses
72	and devices, allowing device drivers to be written independently of
73	bus type.
74  </para>
75  </chapter>
76
77  <chapter id="bugs">
78     <title>Known Bugs And Assumptions</title>
79  <para>
80	None.
81  </para>
82  </chapter>
83
84  <chapter id="mmio">
85    <title>Memory Mapped IO</title>
86    <sect1>
87      <title>Getting Access to the Device</title>
88      <para>
89	The most widely supported form of IO is memory mapped IO.
90	That is, a part of the CPU's address space is interpreted
91	not as accesses to memory, but as accesses to a device.  Some
92	architectures define devices to be at a fixed address, but most
93	have some method of discovering devices.  The PCI bus walk is a
94	good example of such a scheme.	This document does not cover how
95	to receive such an address, but assumes you are starting with one.
96	Physical addresses are of type unsigned long.
97      </para>
98
99      <para>
100	This address should not be used directly.  Instead, to get an
101	address suitable for passing to the accessor functions described
102	below, you should call <function>ioremap</function>.
103	An address suitable for accessing the device will be returned to you.
104      </para>
105
106      <para>
107	After you've finished using the device (say, in your module's
108	exit routine), call <function>iounmap</function> in order to return
109	the address space to the kernel.  Most architectures allocate new
110	address space each time you call <function>ioremap</function>, and
111	they can run out unless you call <function>iounmap</function>.
112      </para>
113    </sect1>
114
115    <sect1>
116      <title>Accessing the device</title>
117      <para>
118	The part of the interface most used by drivers is reading and
119	writing memory-mapped registers on the device.	Linux provides
120	interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit
121	quantities.  Due to a historical accident, these are named byte,
122	word, long and quad accesses.  Both read and write accesses are
123	supported; there is no prefetch support at this time.
124      </para>
125
126      <para>
127	The functions are named <function>readb</function>,
128	<function>readw</function>, <function>readl</function>,
129	<function>readq</function>, <function>writeb</function>,
130	<function>writew</function>, <function>writel</function> and
131	<function>writeq</function>.
132      </para>
133
134      <para>
135	Some devices (such as framebuffers) would like to use larger
136	transfers than 8 bytes at a time.  For these devices, the
137	<function>memcpy_toio</function>, <function>memcpy_fromio</function>
138	and <function>memset_io</function> functions are provided.
139	Do not use memset or memcpy on IO addresses; they
140	are not guaranteed to copy data in order.
141      </para>
142
143      <para>
144	The read and write functions are defined to be ordered. That is the
145	compiler is not permitted to reorder the I/O sequence. When the
146	ordering can be compiler optimised, you can use <function>
147	__readb</function> and friends to indicate the relaxed ordering. Use
148	this with care. The <function>rmb</function> provides a read memory
149	barrier. The <function>wmb</function> provides a write memory barrier.
150      </para>
151
152      <para>
153	While the basic functions are defined to be synchronous with respect
154	to each other and ordered with respect to each other the busses the
155	devices sit on may themselves have asynchronocity. In paticular many
156	authors are burned by the fact that PCI bus writes are posted
157	asynchronously. A driver author must issue a read from the same
158	device to ensure that writes have occurred in the specific cases the
159	author cares. This kind of property cannot be hidden from driver
160	writers in the API.
161      </para>
162    </sect1>
163
164    <sect1>
165      <title>ISA legacy functions</title>
166      <para>
167	On older kernels (2.2 and earlier) the ISA bus could be read or
168	written with these functions and without ioremap being used. This is
169	no longer true in Linux 2.4. A set of equivalent functions exist for
170	easy legacy driver porting. The functions available are prefixed
171	with 'isa_' and are <function>isa_readb</function>,
172	<function>isa_writeb</function>, <function>isa_readw</function>,
173	<function>isa_writew</function>, <function>isa_readl</function>,
174	<function>isa_writel</function>, <function>isa_memcpy_fromio</function>
175	and <function>isa_memcpy_toio</function>
176      </para>
177      <para>
178	These functions should not be used in new drivers, and will
179	eventually be going away.
180      </para>
181    </sect1>
182
183  </chapter>
184
185  <chapter>
186    <title>Port Space Accesses</title>
187    <sect1>
188      <title>Port Space Explained</title>
189
190      <para>
191	Another form of IO commonly supported is Port Space.  This is a
192	range of addresses separate to the normal memory address space.
193	Access to these addresses is generally not as fast as accesses
194	to the memory mapped addresses, and it also has a potentially
195	smaller address space.
196      </para>
197
198      <para>
199	Unlike memory mapped IO, no preparation is required
200	to access port space.
201      </para>
202
203    </sect1>
204    <sect1>
205      <title>Accessing Port Space</title>
206      <para>
207	Accesses to this space are provided through a set of functions
208	which allow 8-bit, 16-bit and 32-bit accesses; also
209	known as byte, word and long.  These functions are
210	<function>inb</function>, <function>inw</function>,
211	<function>inl</function>, <function>outb</function>,
212	<function>outw</function> and <function>outl</function>.
213      </para>
214
215      <para>
216	Some variants are provided for these functions.  Some devices
217	require that accesses to their ports are slowed down.  This
218	functionality is provided by appending a <function>_p</function>
219	to the end of the function.  There are also equivalents to memcpy.
220	The <function>ins</function> and <function>outs</function>
221	functions copy bytes, words or longs to the given port.
222      </para>
223    </sect1>
224
225  </chapter>
226
227  <chapter id="pubfunctions">
228     <title>Public Functions Provided</title>
229!Einclude/asm-i386/io.h
230  </chapter>
231
232</book>
233