tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
io-mapping.txt: standardize document format
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Add a title for the document and for API chapter;
- mark literal blocks;
- Adjust whitespacing.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
9cf5116d
45d85146
+41
-26
+41
-26
Documentation/io-mapping.txt
+41
-26
Documentation/io-mapping.txt
···
1
+
========================
2
+
The io_mapping functions
3
+
========================
4
+
5
+
API
6
+
===
7
+
1
8
The io_mapping functions in linux/io-mapping.h provide an abstraction for
2
9
efficiently mapping small regions of an I/O device to the CPU. The initial
3
10
usage is to support the large graphics aperture on 32-bit processors where
4
11
ioremap_wc cannot be used to statically map the entire aperture to the CPU
5
12
as it would consume too much of the kernel address space.
6
13
7
-
A mapping object is created during driver initialization using
14
+
A mapping object is created during driver initialization using::
8
15
9
16
struct io_mapping *io_mapping_create_wc(unsigned long base,
10
17
unsigned long size)
11
18
12
-
'base' is the bus address of the region to be made
13
-
mappable, while 'size' indicates how large a mapping region to
14
-
enable. Both are in bytes.
19
+
'base' is the bus address of the region to be made
20
+
mappable, while 'size' indicates how large a mapping region to
21
+
enable. Both are in bytes.
15
22
16
-
This _wc variant provides a mapping which may only be used
17
-
with the io_mapping_map_atomic_wc or io_mapping_map_wc.
23
+
This _wc variant provides a mapping which may only be used
24
+
with the io_mapping_map_atomic_wc or io_mapping_map_wc.
18
25
19
26
With this mapping object, individual pages can be mapped either atomically
20
27
or not, depending on the necessary scheduling environment. Of course, atomic
21
-
maps are more efficient:
28
+
maps are more efficient::
22
29
23
30
void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
24
31
unsigned long offset)
25
32
26
-
'offset' is the offset within the defined mapping region.
27
-
Accessing addresses beyond the region specified in the
28
-
creation function yields undefined results. Using an offset
29
-
which is not page aligned yields an undefined result. The
30
-
return value points to a single page in CPU address space.
33
+
'offset' is the offset within the defined mapping region.
34
+
Accessing addresses beyond the region specified in the
35
+
creation function yields undefined results. Using an offset
36
+
which is not page aligned yields an undefined result. The
37
+
return value points to a single page in CPU address space.
31
38
32
-
This _wc variant returns a write-combining map to the
33
-
page and may only be used with mappings created by
34
-
io_mapping_create_wc
39
+
This _wc variant returns a write-combining map to the
40
+
page and may only be used with mappings created by
41
+
io_mapping_create_wc
35
42
36
-
Note that the task may not sleep while holding this page
37
-
mapped.
43
+
Note that the task may not sleep while holding this page
44
+
mapped.
45
+
46
+
::
38
47
39
48
void io_mapping_unmap_atomic(void *vaddr)
40
49
41
-
'vaddr' must be the value returned by the last
42
-
io_mapping_map_atomic_wc call. This unmaps the specified
43
-
page and allows the task to sleep once again.
50
+
'vaddr' must be the value returned by the last
51
+
io_mapping_map_atomic_wc call. This unmaps the specified
52
+
page and allows the task to sleep once again.
44
53
45
54
If you need to sleep while holding the lock, you can use the non-atomic
46
55
variant, although they may be significantly slower.
47
56
57
+
::
58
+
48
59
void *io_mapping_map_wc(struct io_mapping *mapping,
49
60
unsigned long offset)
50
61
51
-
This works like io_mapping_map_atomic_wc except it allows
52
-
the task to sleep while holding the page mapped.
62
+
This works like io_mapping_map_atomic_wc except it allows
63
+
the task to sleep while holding the page mapped.
64
+
65
+
66
+
::
53
67
54
68
void io_mapping_unmap(void *vaddr)
55
69
56
-
This works like io_mapping_unmap_atomic, except it is used
57
-
for pages mapped with io_mapping_map_wc.
70
+
This works like io_mapping_unmap_atomic, except it is used
71
+
for pages mapped with io_mapping_map_wc.
58
72
59
-
At driver close time, the io_mapping object must be freed:
73
+
At driver close time, the io_mapping object must be freed::
60
74
61
75
void io_mapping_free(struct io_mapping *mapping)
62
76
63
-
Current Implementation:
77
+
Current Implementation
78
+
======================
64
79
65
80
The initial implementation of these functions uses existing mapping
66
81
mechanisms and so provides only an abstraction layer and no new