Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) The io_mapping functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) ===
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) The io_mapping functions in linux/io-mapping.h provide an abstraction for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) efficiently mapping small regions of an I/O device to the CPU. The initial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) usage is to support the large graphics aperture on 32-bit processors where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ioremap_wc cannot be used to statically map the entire aperture to the CPU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) as it would consume too much of the kernel address space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) A mapping object is created during driver initialization using::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 	struct io_mapping *io_mapping_create_wc(unsigned long base,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) 						unsigned long size)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 'base' is the bus address of the region to be made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) mappable, while 'size' indicates how large a mapping region to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) enable. Both are in bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) This _wc variant provides a mapping which may only be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) with the io_mapping_map_atomic_wc or io_mapping_map_wc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) With this mapping object, individual pages can be mapped either atomically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) or not, depending on the necessary scheduling environment. Of course, atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) maps are more efficient::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) 	void *io_mapping_map_atomic_wc(struct io_mapping *mapping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 				       unsigned long offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 'offset' is the offset within the defined mapping region.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Accessing addresses beyond the region specified in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) creation function yields undefined results. Using an offset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) which is not page aligned yields an undefined result. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) return value points to a single page in CPU address space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) This _wc variant returns a write-combining map to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) page and may only be used with mappings created by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) io_mapping_create_wc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Note that the task may not sleep while holding this page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) 	void io_mapping_unmap_atomic(void *vaddr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 'vaddr' must be the value returned by the last
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) io_mapping_map_atomic_wc call. This unmaps the specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) page and allows the task to sleep once again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) If you need to sleep while holding the lock, you can use the non-atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) variant, although they may be significantly slower.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 	void *io_mapping_map_wc(struct io_mapping *mapping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 				unsigned long offset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) This works like io_mapping_map_atomic_wc except it allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) the task to sleep while holding the page mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 	void io_mapping_unmap(void *vaddr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) This works like io_mapping_unmap_atomic, except it is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) for pages mapped with io_mapping_map_wc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) At driver close time, the io_mapping object must be freed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) 	void io_mapping_free(struct io_mapping *mapping)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Current Implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) The initial implementation of these functions uses existing mapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) mechanisms and so provides only an abstraction layer and no new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) On 64-bit processors, io_mapping_create_wc calls ioremap_wc for the whole
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) range, creating a permanent kernel-visible mapping to the resource. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) map_atomic and map functions add the requested offset to the base of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) virtual address returned by ioremap_wc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) On 32-bit processors with HIGHMEM defined, io_mapping_map_atomic_wc uses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) kmap_atomic_pfn to map the specified page in an atomic fashion;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) kmap_atomic_pfn isn't really supposed to be used with device pages, but it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) provides an efficient mapping for this usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) On 32-bit processors without HIGHMEM defined, io_mapping_map_atomic_wc and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) io_mapping_map_wc both use ioremap_wc, a terribly inefficient function which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) performs an IPI to inform all processors about the new mapping. This results
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) in a significant performance penalty.