Documentation/core-api/dma-api-howto.rst

Source file repositories/reference/linux-study-clean/Documentation/core-api/dma-api-howto.rst

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/dma-api-howto.rst
Extension
.rst
Size
35316 bytes
Lines
988
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct my_device {
		spinlock_t lock1;
		__dma_from_device_group_begin();
		char dma_buffer1[16];
		char dma_buffer2[16];
		__dma_from_device_group_end();
		spinlock_t lock2;
	};

To isolate a DMA buffer from adjacent fields, use
``__dma_from_device_group_begin(GROUP)`` before the first DMA buffer
field and ``__dma_from_device_group_end(GROUP)`` after the last DMA
buffer field (with the same GROUP name). This protects both the head
and tail of the buffer from cache line sharing.

The GROUP parameter is an optional identifier that names the DMA buffer group
(in case you have several in the same structure)::

	struct my_device {
		spinlock_t lock1;
		__dma_from_device_group_begin(buffer1);
		char dma_buffer1[16];
		__dma_from_device_group_end(buffer1);
		spinlock_t lock2;
		__dma_from_device_group_begin(buffer2);
		char dma_buffer2[16];
		__dma_from_device_group_end(buffer2);
	};

On cache-coherent platforms these macros expand to zero-length array markers.
On non-coherent platforms, they also ensure the minimal DMA alignment, which
can be as large as 128 bytes.

.. note::

        It is allowed (though somewhat fragile) to include extra fields, not
        intended for DMA from the device, within the group (in order to pack the
        structure tightly) - but only as long as the CPU does not write these
        fields while any fields in the group are mapped for DMA_FROM_DEVICE or
        DMA_BIDIRECTIONAL.

DMA addressing capabilities
===========================

By default, the kernel assumes that your device can address 32-bits of DMA
addressing.  For a 64-bit capable device, this needs to be increased, and for
a device with limitations, it needs to be decreased.

Special note about PCI: PCI-X specification requires PCI-X devices to support
64-bit addressing (DAC) for all transactions.  And at least one platform (SGI
SN2) requires 64-bit coherent allocations to operate correctly when the IO
bus is in PCI-X mode.

For correct operation, you must set the DMA mask to inform the kernel about
your devices DMA addressing capabilities.

This is performed via a call to dma_set_mask_and_coherent()::

	int dma_set_mask_and_coherent(struct device *dev, u64 mask);

which will set the mask for both streaming and coherent APIs together.  If you
have some special requirements, then the following two separate calls can be
used instead:

	The setup for streaming mappings is performed via a call to
	dma_set_mask()::

		int dma_set_mask(struct device *dev, u64 mask);

	The setup for coherent allocations is performed via a call

Annotation

Implementation Notes