| 1 | ========================
|
| 2 | The io_mapping functions
|
| 3 | ========================
|
| 4 |
|
| 5 | API
|
| 6 | ===
|
| 7 |
|
| 8 | The io_mapping functions in linux/io-mapping.h provide an abstraction for
|
| 9 | efficiently mapping small regions of an I/O device to the CPU. The initial
|
| 10 | usage is to support the large graphics aperture on 32-bit processors where
|
| 11 | ioremap_wc cannot be used to statically map the entire aperture to the CPU
|
| 12 | as it would consume too much of the kernel address space.
|
| 13 |
|
| 14 | A mapping object is created during driver initialization using::
|
| 15 |
|
| 16 | struct io_mapping *io_mapping_create_wc(unsigned long base,
|
| 17 | unsigned long size)
|
| 18 |
|
| 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.
|
| 22 |
|
| 23 | This _wc variant provides a mapping which may only be used with
|
| 24 | io_mapping_map_atomic_wc(), io_mapping_map_local_wc() or
|
| 25 | io_mapping_map_wc().
|
| 26 |
|
| 27 | With this mapping object, individual pages can be mapped either temporarily
|
| 28 | or long term, depending on the requirements. Of course, temporary maps are
|
| 29 | more efficient. They come in two flavours::
|
| 30 |
|
| 31 | void *io_mapping_map_local_wc(struct io_mapping *mapping,
|
| 32 | unsigned long offset)
|
| 33 |
|
| 34 | void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
|
| 35 | unsigned long offset)
|
| 36 |
|
| 37 | 'offset' is the offset within the defined mapping region. Accessing
|
| 38 | addresses beyond the region specified in the creation function yields
|
| 39 | undefined results. Using an offset which is not page aligned yields an
|
| 40 | undefined result. The return value points to a single page in CPU address
|
| 41 | space.
|
| 42 |
|
| 43 | This _wc variant returns a write-combining map to the page and may only be
|
| 44 | used with mappings created by io_mapping_create_wc()
|
| 45 |
|
| 46 | Temporary mappings are only valid in the context of the caller. The mapping
|
| 47 | is not guaranteed to be globally visible.
|
| 48 |
|
| 49 | io_mapping_map_local_wc() has a side effect on X86 32bit as it disables
|
| 50 | migration to make the mapping code work. No caller can rely on this side
|
| 51 | effect.
|
| 52 |
|
| 53 | io_mapping_map_atomic_wc() has the side effect of disabling preemption and
|
| 54 | pagefaults. Don't use in new code. Use io_mapping_map_local_wc() instead.
|
| 55 |
|
| 56 | Nested mappings need to be undone in reverse order because the mapping
|
| 57 | code uses a stack for keeping track of them::
|
| 58 |
|
| 59 | addr1 = io_mapping_map_local_wc(map1, offset1);
|
| 60 | addr2 = io_mapping_map_local_wc(map2, offset2);
|
| 61 | ...
|
| 62 | io_mapping_unmap_local(addr2);
|
| 63 | io_mapping_unmap_local(addr1);
|
| 64 |
|
| 65 | The mappings are released with::
|
| 66 |
|
| 67 | void io_mapping_unmap_local(void *vaddr)
|
| 68 | void io_mapping_unmap_atomic(void *vaddr)
|
| 69 |
|
| 70 | 'vaddr' must be the value returned by the last io_mapping_map_local_wc() or
|
| 71 | io_mapping_map_atomic_wc() call. This unmaps the specified mapping and
|
| 72 | undoes the side effects of the mapping functions.
|
| 73 |
|
| 74 | If you need to sleep while holding a mapping, you can use the regular
|
| 75 | variant, although this may be significantly slower::
|
| 76 |
|
| 77 | void *io_mapping_map_wc(struct io_mapping *mapping,
|
| 78 | unsigned long offset)
|
| 79 |
|
| 80 | This works like io_mapping_map_atomic/local_wc() except it has no side
|
| 81 | effects and the pointer is globally visible.
|
| 82 |
|
| 83 | The mappings are released with::
|
| 84 |
|
| 85 | void io_mapping_unmap(void *vaddr)
|
| 86 |
|
| 87 | Use for pages mapped with io_mapping_map_wc().
|
| 88 |
|
| 89 | At driver close time, the io_mapping object must be freed::
|
| 90 |
|
| 91 | void io_mapping_free(struct io_mapping *mapping)
|