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>zero-colors
parent
45d8514626
commit
9cf5116d5b
|
@ -1,10 +1,17 @@
|
||||||
|
========================
|
||||||
|
The io_mapping functions
|
||||||
|
========================
|
||||||
|
|
||||||
|
API
|
||||||
|
===
|
||||||
|
|
||||||
The io_mapping functions in linux/io-mapping.h provide an abstraction for
|
The io_mapping functions in linux/io-mapping.h provide an abstraction for
|
||||||
efficiently mapping small regions of an I/O device to the CPU. The initial
|
efficiently mapping small regions of an I/O device to the CPU. The initial
|
||||||
usage is to support the large graphics aperture on 32-bit processors where
|
usage is to support the large graphics aperture on 32-bit processors where
|
||||||
ioremap_wc cannot be used to statically map the entire aperture to the CPU
|
ioremap_wc cannot be used to statically map the entire aperture to the CPU
|
||||||
as it would consume too much of the kernel address space.
|
as it would consume too much of the kernel address space.
|
||||||
|
|
||||||
A mapping object is created during driver initialization using
|
A mapping object is created during driver initialization using::
|
||||||
|
|
||||||
struct io_mapping *io_mapping_create_wc(unsigned long base,
|
struct io_mapping *io_mapping_create_wc(unsigned long base,
|
||||||
unsigned long size)
|
unsigned long size)
|
||||||
|
@ -18,7 +25,7 @@ A mapping object is created during driver initialization using
|
||||||
|
|
||||||
With this mapping object, individual pages can be mapped either atomically
|
With this mapping object, individual pages can be mapped either atomically
|
||||||
or not, depending on the necessary scheduling environment. Of course, atomic
|
or not, depending on the necessary scheduling environment. Of course, atomic
|
||||||
maps are more efficient:
|
maps are more efficient::
|
||||||
|
|
||||||
void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
|
void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
|
||||||
unsigned long offset)
|
unsigned long offset)
|
||||||
|
@ -36,6 +43,8 @@ maps are more efficient:
|
||||||
Note that the task may not sleep while holding this page
|
Note that the task may not sleep while holding this page
|
||||||
mapped.
|
mapped.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
void io_mapping_unmap_atomic(void *vaddr)
|
void io_mapping_unmap_atomic(void *vaddr)
|
||||||
|
|
||||||
'vaddr' must be the value returned by the last
|
'vaddr' must be the value returned by the last
|
||||||
|
@ -45,22 +54,28 @@ maps are more efficient:
|
||||||
If you need to sleep while holding the lock, you can use the non-atomic
|
If you need to sleep while holding the lock, you can use the non-atomic
|
||||||
variant, although they may be significantly slower.
|
variant, although they may be significantly slower.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
void *io_mapping_map_wc(struct io_mapping *mapping,
|
void *io_mapping_map_wc(struct io_mapping *mapping,
|
||||||
unsigned long offset)
|
unsigned long offset)
|
||||||
|
|
||||||
This works like io_mapping_map_atomic_wc except it allows
|
This works like io_mapping_map_atomic_wc except it allows
|
||||||
the task to sleep while holding the page mapped.
|
the task to sleep while holding the page mapped.
|
||||||
|
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
void io_mapping_unmap(void *vaddr)
|
void io_mapping_unmap(void *vaddr)
|
||||||
|
|
||||||
This works like io_mapping_unmap_atomic, except it is used
|
This works like io_mapping_unmap_atomic, except it is used
|
||||||
for pages mapped with io_mapping_map_wc.
|
for pages mapped with io_mapping_map_wc.
|
||||||
|
|
||||||
At driver close time, the io_mapping object must be freed:
|
At driver close time, the io_mapping object must be freed::
|
||||||
|
|
||||||
void io_mapping_free(struct io_mapping *mapping)
|
void io_mapping_free(struct io_mapping *mapping)
|
||||||
|
|
||||||
Current Implementation:
|
Current Implementation
|
||||||
|
======================
|
||||||
|
|
||||||
The initial implementation of these functions uses existing mapping
|
The initial implementation of these functions uses existing mapping
|
||||||
mechanisms and so provides only an abstraction layer and no new
|
mechanisms and so provides only an abstraction layer and no new
|
||||||
|
|
Loading…
Reference in New Issue