Documentation/core-api/dma-api.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/core-api/dma-api.rst
Extension
.rst
Size
32325 bytes
Lines
869
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

============================================
Dynamic DMA mapping using the generic device
============================================

:Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>

This document describes the DMA API.  For a more gentle introduction
of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst.

This API is split into two pieces.  Part I describes the basic API.
Part II describes extensions for supporting non-coherent memory
machines.  Unless you know that your driver absolutely has to support
non-coherent platforms (this is usually only legacy platforms) you
should only use the API described in part I.

Part I - DMA API
----------------

To get the DMA API, you must #include <linux/dma-mapping.h>.  This
provides dma_addr_t and the interfaces described below.

A dma_addr_t can hold any valid DMA address for the platform.  It can be
given to a device to use as a DMA source or target.  A CPU cannot reference
a dma_addr_t directly because there may be translation between its physical
address space and the DMA address space.

Part Ia - Using large DMA-coherent buffers
------------------------------------------

::

	void *
	dma_alloc_coherent(struct device *dev, size_t size,
			   dma_addr_t *dma_handle, gfp_t flag)

Coherent memory is memory for which a write by either the device or
the processor can immediately be read by the processor or device
without having to worry about caching effects.  (You may however need
to make sure to flush the processor's write buffers before telling
devices to read that memory.)

This routine allocates a region of <size> bytes of coherent memory.

It returns a pointer to the allocated region (in the processor's virtual
address space) or NULL if the allocation failed.

It also returns a <dma_handle> which may be cast to an unsigned integer the
same width as the bus and given to the device as the DMA address base of
the region.

Note: coherent memory can be expensive on some platforms, and the
minimum allocation length may be as big as a page, so you should
consolidate your requests for coherent memory as much as possible.
The simplest way to do that is to use the dma_pool calls (see below).

The flag parameter allows the caller to specify the ``GFP_`` flags (see
kmalloc()) for the allocation (the implementation may ignore flags that affect
the location of the returned memory, like GFP_DMA).

::

	void
	dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
			  dma_addr_t dma_handle)

Free a previously allocated region of coherent memory.  dev, size and dma_handle
must all be the same as those passed into dma_alloc_coherent().  cpu_addr must
be the virtual address returned by dma_alloc_coherent().

Note that unlike the sibling allocation call, this routine may only be called

Annotation

Implementation Notes