From 6778948f9de86c3cfaf36725a7c87dcff9ba247f Mon Sep 17 00:00:00 2001 From: hc <hc@nodka.com> Date: Mon, 11 Dec 2023 08:20:59 +0000 Subject: [PATCH] kernel_5.10 no rt --- kernel/Documentation/driver-api/io-mapping.rst | 92 ++++++++++++++++++++++++++------------------- 1 files changed, 53 insertions(+), 39 deletions(-) diff --git a/kernel/Documentation/driver-api/io-mapping.rst b/kernel/Documentation/driver-api/io-mapping.rst index a7830c5..a966239 100644 --- a/kernel/Documentation/driver-api/io-mapping.rst +++ b/kernel/Documentation/driver-api/io-mapping.rst @@ -20,64 +20,78 @@ mappable, while 'size' indicates how large a mapping region to enable. Both are in bytes. -This _wc variant provides a mapping which may only be used with -io_mapping_map_local_wc() or io_mapping_map_wc(). +This _wc variant provides a mapping which may only be used +with the io_mapping_map_atomic_wc or io_mapping_map_wc. -With this mapping object, individual pages can be mapped either temporarily -or long term, depending on the requirements. Of course, temporary maps are -more efficient. +With this mapping object, individual pages can be mapped either atomically +or not, depending on the necessary scheduling environment. Of course, atomic +maps are more efficient:: - void *io_mapping_map_local_wc(struct io_mapping *mapping, - unsigned long offset) + void *io_mapping_map_atomic_wc(struct io_mapping *mapping, + unsigned long offset) -'offset' is the offset within the defined mapping region. Accessing -addresses beyond the region specified in the creation function yields -undefined results. Using an offset which is not page aligned yields an -undefined result. The return value points to a single page in CPU address -space. +'offset' is the offset within the defined mapping region. +Accessing addresses beyond the region specified in the +creation function yields undefined results. Using an offset +which is not page aligned yields an undefined result. The +return value points to a single page in CPU address space. -This _wc variant returns a write-combining map to the page and may only be -used with mappings created by io_mapping_create_wc() +This _wc variant returns a write-combining map to the +page and may only be used with mappings created by +io_mapping_create_wc -Temporary mappings are only valid in the context of the caller. The mapping -is not guaranteed to be globaly visible. +Note that the task may not sleep while holding this page +mapped. -io_mapping_map_local_wc() has a side effect on X86 32bit as it disables -migration to make the mapping code work. No caller can rely on this side -effect. +:: -Nested mappings need to be undone in reverse order because the mapping -code uses a stack for keeping track of them:: + void io_mapping_unmap_atomic(void *vaddr) - addr1 = io_mapping_map_local_wc(map1, offset1); - addr2 = io_mapping_map_local_wc(map2, offset2); - ... - io_mapping_unmap_local(addr2); - io_mapping_unmap_local(addr1); +'vaddr' must be the value returned by the last +io_mapping_map_atomic_wc call. This unmaps the specified +page and allows the task to sleep once again. -The mappings are released with:: +If you need to sleep while holding the lock, you can use the non-atomic +variant, although they may be significantly slower. - void io_mapping_unmap_local(void *vaddr) - -'vaddr' must be the value returned by the last io_mapping_map_local_wc() -call. This unmaps the specified mapping and undoes eventual side effects of -the mapping function. - -If you need to sleep while holding a mapping, you can use the regular -variant, although this may be significantly slower:: +:: void *io_mapping_map_wc(struct io_mapping *mapping, unsigned long offset) -This works like io_mapping_map_local_wc() except it has no side effects and -the pointer is globaly visible. +This works like io_mapping_map_atomic_wc except it allows +the task to sleep while holding the page mapped. -The mappings are released with:: + +:: void io_mapping_unmap(void *vaddr) -Use for pages mapped with io_mapping_map_wc(). +This works like io_mapping_unmap_atomic, except it is used +for pages mapped with io_mapping_map_wc. At driver close time, the io_mapping object must be freed:: void io_mapping_free(struct io_mapping *mapping) + +Current Implementation +====================== + +The initial implementation of these functions uses existing mapping +mechanisms and so provides only an abstraction layer and no new +functionality. + +On 64-bit processors, io_mapping_create_wc calls ioremap_wc for the whole +range, creating a permanent kernel-visible mapping to the resource. The +map_atomic and map functions add the requested offset to the base of the +virtual address returned by ioremap_wc. + +On 32-bit processors with HIGHMEM defined, io_mapping_map_atomic_wc uses +kmap_atomic_pfn to map the specified page in an atomic fashion; +kmap_atomic_pfn isn't really supposed to be used with device pages, but it +provides an efficient mapping for this usage. + +On 32-bit processors without HIGHMEM defined, io_mapping_map_atomic_wc and +io_mapping_map_wc both use ioremap_wc, a terribly inefficient function which +performs an IPI to inform all processors about the new mapping. This results +in a significant performance penalty. -- Gitblit v1.6.2