0001 ========================
0002 The io_mapping functions
0003 ========================
0004
0005 API
0006 ===
0007
0008 The io_mapping functions in linux/io-mapping.h provide an abstraction for
0009 efficiently mapping small regions of an I/O device to the CPU. The initial
0010 usage is to support the large graphics aperture on 32-bit processors where
0011 ioremap_wc cannot be used to statically map the entire aperture to the CPU
0012 as it would consume too much of the kernel address space.
0013
0014 A mapping object is created during driver initialization using::
0015
0016 struct io_mapping *io_mapping_create_wc(unsigned long base,
0017 unsigned long size)
0018
0019 'base' is the bus address of the region to be made
0020 mappable, while 'size' indicates how large a mapping region to
0021 enable. Both are in bytes.
0022
0023 This _wc variant provides a mapping which may only be used with
0024 io_mapping_map_atomic_wc(), io_mapping_map_local_wc() or
0025 io_mapping_map_wc().
0026
0027 With this mapping object, individual pages can be mapped either temporarily
0028 or long term, depending on the requirements. Of course, temporary maps are
0029 more efficient. They come in two flavours::
0030
0031 void *io_mapping_map_local_wc(struct io_mapping *mapping,
0032 unsigned long offset)
0033
0034 void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
0035 unsigned long offset)
0036
0037 'offset' is the offset within the defined mapping region. Accessing
0038 addresses beyond the region specified in the creation function yields
0039 undefined results. Using an offset which is not page aligned yields an
0040 undefined result. The return value points to a single page in CPU address
0041 space.
0042
0043 This _wc variant returns a write-combining map to the page and may only be
0044 used with mappings created by io_mapping_create_wc()
0045
0046 Temporary mappings are only valid in the context of the caller. The mapping
0047 is not guaranteed to be globaly visible.
0048
0049 io_mapping_map_local_wc() has a side effect on X86 32bit as it disables
0050 migration to make the mapping code work. No caller can rely on this side
0051 effect.
0052
0053 io_mapping_map_atomic_wc() has the side effect of disabling preemption and
0054 pagefaults. Don't use in new code. Use io_mapping_map_local_wc() instead.
0055
0056 Nested mappings need to be undone in reverse order because the mapping
0057 code uses a stack for keeping track of them::
0058
0059 addr1 = io_mapping_map_local_wc(map1, offset1);
0060 addr2 = io_mapping_map_local_wc(map2, offset2);
0061 ...
0062 io_mapping_unmap_local(addr2);
0063 io_mapping_unmap_local(addr1);
0064
0065 The mappings are released with::
0066
0067 void io_mapping_unmap_local(void *vaddr)
0068 void io_mapping_unmap_atomic(void *vaddr)
0069
0070 'vaddr' must be the value returned by the last io_mapping_map_local_wc() or
0071 io_mapping_map_atomic_wc() call. This unmaps the specified mapping and
0072 undoes the side effects of the mapping functions.
0073
0074 If you need to sleep while holding a mapping, you can use the regular
0075 variant, although this may be significantly slower::
0076
0077 void *io_mapping_map_wc(struct io_mapping *mapping,
0078 unsigned long offset)
0079
0080 This works like io_mapping_map_atomic/local_wc() except it has no side
0081 effects and the pointer is globaly visible.
0082
0083 The mappings are released with::
0084
0085 void io_mapping_unmap(void *vaddr)
0086
0087 Use for pages mapped with io_mapping_map_wc().
0088
0089 At driver close time, the io_mapping object must be freed::
0090
0091 void io_mapping_free(struct io_mapping *mapping)
