DMA_ATTR_WEAK_ORDERING¶

DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mappingmay be weakly ordered, that is that reads and writes may pass each other.

Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING,those that do not will simply ignore the attribute and exhibit defaultbehavior.

DMA_ATTR_WRITE_COMBINE¶

DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may bebuffered to improve performance.

Since it is optional for platforms to implement DMA_ATTR_WRITE_COMBINE,those that do not will simply ignore the attribute and exhibit defaultbehavior.

DMA_ATTR_NO_KERNEL_MAPPING¶

DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernelvirtual mapping for the allocated buffer. On some architectures creatingsuch mapping is non-trivial task and consumes very limited resources(like kernel virtual address space or dma consistent address space).Buffers allocated with this attribute can be only passed to user spaceby callingdma_mmap_attrs(). By using this API, you are guaranteeingthat you won’t dereference the pointer returned bydma_alloc_attr(). Youcan treat it as a cookie that must be passed todma_mmap_attrs() anddma_free_attrs(). Make sure that both of these also get this attributeset on each call.

Since it is optional for platforms to implementDMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore theattribute and exhibit default behavior.

DMA_ATTR_SKIP_CPU_SYNC¶

By default dma_map_{single,page,sg} functions family transfer a givenbuffer from CPU domain to device domain. Some advanced use cases mightrequire sharing a buffer between more than one device. This requireshaving a mapping created separately for each device and is usuallyperformed by calling dma_map_{single,page,sg} function more than oncefor the given buffer with device pointer to each device taking part inthe buffer sharing. The first call transfers a buffer from ‘CPU’ domainto ‘device’ domain, what synchronizes CPU caches for the given region(usually it means that the cache has been flushed or invalidateddepending on the dma direction). However, next calls todma_map_{single,page,sg}() for other devices will perform exactly thesame synchronization operation on the CPU cache. CPU cache synchronizationmight be a time consuming operation, especially if the buffers arelarge, so it is highly recommended to avoid it if possible.DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization ofthe CPU cache for the given buffer assuming that it has been alreadytransferred to ‘device’ domain. This attribute can be also used fordma_unmap_{single,page,sg} functions family to force buffer to stay indevice domain after releasing a mapping for it. Use this attribute withcare!

DMA_ATTR_FORCE_CONTIGUOUS¶

By default DMA-mapping subsystem is allowed to assemble the bufferallocated bydma_alloc_attrs() function from individual pages if it canbe mapped as contiguous chunk into device dma address space. Byspecifying this attribute the allocated buffer is forced to be contiguousalso in physical memory.

DMA_ATTR_ALLOC_SINGLE_PAGES¶

This is a hint to the DMA-mapping subsystem that it’s probably not worththe time to try to allocate memory to in a way that gives better TLBefficiency (AKA it’s not worth trying to build the mapping out of largerpages). 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 orthat they aren’t sequential but it’s unlikely you’ll ping-pongbetween many addresses that are likely to be in different physicalpages.

• You know that the penalty of TLB misses while accessing thememory will be small enough to be inconsequential. If you aredoing a heavy operation like decryption or decompression thismight be the case.

• You know that the DMA mapping is fairly transitory. If you expectthe mapping to have a short lifetime then it may be worth it tooptimize allocation (avoid coming up with large pages) instead ofgetting the slight performance win of larger pages.

Setting this hint doesn’t guarantee that you won’t get huge pages, but itmeans that we won’t try quite as hard to get them.

DMA_ATTR_NO_WARN¶

This tells the DMA-mapping subsystem to suppress allocation failure reports(similarly to __GFP_NOWARN).

On some architectures allocation failures are reported with error messagesto the system logs. Although this can help to identify and debug problems,drivers which handle failures (eg, retry later) have no problems with them,and can actually flood the system logs with error messages that aren’t anyproblem at all, depending on the implementation of the retry mechanism.

So, this provides a way for drivers to avoid those error messages on callswhere allocation failures are not a problem, and shouldn’t bother the logs.

DMA_ATTR_PRIVILEGED¶

Some advanced peripherals such as remote processors and GPUs performaccesses to DMA buffers in both privileged “supervisor” and unprivileged“user” modes. This attribute is used to indicate to the DMA-mappingsubsystem that the buffer is fully accessible at the elevated privilegelevel (and ideally inaccessible or at least read-only at thelesser-privileged levels).

DMA_ATTR_MMIO¶

This attribute indicates the physical address is not normal systemmemory. It may not be used with kmap*()/phys_to_virt()/phys_to_page()functions, it may not be cacheable, and access using CPU load/storeinstructions may not be allowed.

Usually this will be used to describe MMIO addresses, or other non-cacheableregister addresses. When DMA mapping this sort of address we callthe operation Peer to Peer as a one device is DMA’ing to another device.For PCI devices the p2pdma APIs must be used to determine ifDMA_ATTR_MMIO is appropriate.

For architectures that require cache flushing for DMA coherenceDMA_ATTR_MMIO will not perform any cache flushing. The addressprovided must never be mapped cacheable into the CPU.