change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/driver-api/device-io.rst
..
..
@@ -36,14 +36,14 @@
36
36
 
37
37
 This address should not be used directly. Instead, to get an address
38
38
 suitable for passing to the accessor functions described below, you
39
-should call :c:func:`ioremap()`. An address suitable for accessing
39
+should call ioremap(). An address suitable for accessing
40
40
 the device will be returned to you.
41
41
 
42
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
43
+routine), call iounmap() in order to return the address
44
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()`.
45
+time you call ioremap(), and they can run out unless you
46
+call iounmap().
47
47
 
48
48
 Accessing the device
49
49
 --------------------
..
..
@@ -60,8 +60,8 @@
60
60
 writeb(), writew(), writel() and writeq().
61
61
 
62
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
63
+8 bytes at a time. For these devices, the memcpy_toio(),
64
+memcpy_fromio() and memset_io() functions are
65
65
 provided. Do not use memset or memcpy on IO addresses; they are not
66
66
 guaranteed to copy data in order.
67
67
 
..
..
@@ -103,51 +103,6 @@
103
103
         ha->flags.ints_enabled = 0;
104
104
     }
105
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
106
 PCI ordering rules also guarantee that PIO read responses arrive after any
152
107
 outstanding DMA writes from that bus, since for some devices the result of
153
108
 a readb() call may signal to the driver that a DMA transaction is
..
..
@@ -180,15 +135,15 @@
180
135
 
181
136
 Accesses to this space are provided through a set of functions which
182
137
 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()`.
138
+long. These functions are inb(), inw(),
139
+inl(), outb(), outw() and
140
+outl().
186
141
 
187
142
 Some variants are provided for these functions. Some devices require
188
143
 that accesses to their ports are slowed down. This functionality is
189
144
 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
145
+There are also equivalents to memcpy. The ins() and
146
+outs() functions copy bytes, words or longs to the given
192
147
 port.
193
148
 
194
149
 Public Functions Provided