--- zzzz-none-000/linux-3.10.107/Documentation/DMA-attributes.txt 2017-06-27 09:49:32.000000000 +0000 +++ scorpion-7490-727/linux-3.10.107/Documentation/DMA-attributes.txt 2021-02-04 17:41:59.000000000 +0000 @@ -13,7 +13,7 @@ strictly order DMA from a device across all intervening busses and bridges. This barrier is not specific to a particular type of interconnect, it applies to the system as a whole, and so its -implementation must account for the idiosyncracies of the system all +implementation must account for the idiosyncrasies of the system all the way from the DMA device to memory. As an example of a situation where DMA_ATTR_WRITE_BARRIER would be @@ -60,7 +60,7 @@ Buffers allocated with this attribute can be only passed to user space by calling dma_mmap_attrs(). By using this API, you are guaranteeing that you won't dereference the pointer returned by dma_alloc_attr(). You -can threat it as a cookie that must be passed to dma_mmap_attrs() and +can treat it as a cookie that must be passed to dma_mmap_attrs() and dma_free_attrs(). Make sure that both of these also get this attribute set on each call. @@ -82,7 +82,7 @@ (usually it means that the cache has been flushed or invalidated depending on the dma direction). However, next calls to dma_map_{single,page,sg}() for other devices will perform exactly the -same sychronization operation on the CPU cache. CPU cache sychronization +same synchronization operation on the CPU cache. CPU cache synchronization might be a time consuming operation, especially if the buffers are large, so it is highly recommended to avoid it if possible. DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization of @@ -98,5 +98,76 @@ By default DMA-mapping subsystem is allowed to assemble the buffer allocated by dma_alloc_attrs() function from individual pages if it can be mapped as contiguous chunk into device dma address space. By -specifing this attribute the allocated buffer is forced to be contiguous +specifying this attribute the allocated buffer is forced to be contiguous also in physical memory. + +DMA_ATTR_STRONGLY_ORDERED +------------------------- + +DMA_ATTR_STRONGLY_ORDERED allocates memory with a very restrictive type +of mapping (no unaligned accesses, no re-ordering, no write merging, no +buffering, no pre-fetching). This has severe performance penalties and +should not be used for general purpose DMA allocations. It should only +be used if one of the restrictions on strongly ordered memory is required. + +DMA_ATTR_NO_DELAYED_UNMAP +------------------------- + +DMA_ATTR_NO_DELAYED_UNMAP is used only by the msm specific lazy mapping +feature. By default, the lazy mapping and unmapping holds an additional +reference so that when the buffer is freed, the mapping is not destroyed +and can be re-used. By specifying this attribute, an additional reference +will NOT be held by the lazy mapping code and it will be released as soon +as the buffer is freed. + +DMA_ATTR_EXEC_MAPPING +--------------------- + +By default, the DMA mappings are non-executable. Some use cases might require +an executable mapping. This attribute can be used to indicate to the DMA +subsystem to create an executable mappings for the buffer. + +DMA_ATTR_FORCE_COHERENT +----------------------- + +When passed to a DMA map call the DMA_ATTR_FORCE_COHERENT DMA +attribute can be used to force a buffer to be mapped as IO coherent. +This DMA attribute is only currently supported for arm64 stage 1 IOMMU +mappings. + +DMA_ATTR_FORCE_NON_COHERENT +--------------------------- +When passed to a DMA map call the DMA_ATTR_FORCE_NON_COHERENT DMA +attribute can be used to force a buffer to not be mapped as IO +coherent. +The DMA_ATTR_FORCE_NON_COHERENT DMA attribute overrides the buffer IO +coherency configuration set by making the device IO coherent. + +This DMA attribute is only currently supported for arm64 stage 1 IOMMU +mappings. + +DMA_ATTR_ALLOC_SINGLE_PAGES +--------------------------- + +This is a hint to the DMA-mapping subsystem that it's probably not worth +the time to try to allocate memory to in a way that gives better TLB +efficiency (AKA it's not worth trying to build the mapping out of larger +pages). You might want to specify this if: +- You know that the accesses to this memory won't thrash the TLB. + You might know that the accesses are likely to be sequential or + that they aren't sequential but it's unlikely you'll ping-pong + between many addresses that are likely to be in different physical + pages. +- You know that the penalty of TLB misses while accessing the + memory will be small enough to be inconsequential. If you are + doing a heavy operation like decryption or decompression this + might be the case. +- You know that the DMA mapping is fairly transitory. If you expect + the mapping to have a short lifetime then it may be worth it to + optimize allocation (avoid coming up with large pages) instead of + getting the slight performance win of larger pages. +Setting this hint doesn't guarantee that you won't get huge pages, but it +means that we won't try quite as hard to get them. + +NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM, +though ARM64 patches will likely be posted soon.