Documentation/core-api/dma-isa-lpc.rst

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

File Facts

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

============================
DMA with ISA and LPC devices
============================

:Author: Pierre Ossman <drzeus@drzeus.cx>

This document describes how to do DMA transfers using the old ISA DMA
controller. Even though ISA is more or less dead today the LPC bus
uses the same DMA system so it will be around for quite some time.

Headers and dependencies
------------------------

To do ISA style DMA you need to include two headers::

	#include <linux/dma-mapping.h>
	#include <asm/dma.h>

The first is the generic DMA API used to convert virtual addresses to
bus addresses (see Documentation/core-api/dma-api.rst for details).

The second contains the routines specific to ISA DMA transfers. Since
this is not present on all platforms make sure you construct your
Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
to build your driver on unsupported platforms.

Buffer allocation
-----------------

The ISA DMA controller has some very strict requirements on which
memory it can access so extra care must be taken when allocating
buffers.

(You usually need a special buffer for DMA transfers instead of
transferring directly to and from your normal data structures.)

The DMA-able address space is the lowest 16 MB of _physical_ memory.
Also the transfer block may not cross page boundaries (which are 64
or 128 KiB depending on which channel you use).

In order to allocate a piece of memory that satisfies all these
requirements you pass the flag GFP_DMA to kmalloc.

Unfortunately the memory available for ISA DMA is scarce so unless you
allocate the memory during boot-up it's a good idea to also pass
__GFP_RETRY_MAYFAIL and __GFP_NOWARN to make the allocator try a bit harder.

(This scarcity also means that you should allocate the buffer as
early as possible and not release it until the driver is unloaded.)

Address translation
-------------------

To translate the virtual address to a bus address, use the normal DMA
API. Do _not_ use isa_virt_to_bus() even though it does the same
thing. The reason for this is that the function isa_virt_to_bus()
will require a Kconfig dependency to ISA, not just ISA_DMA_API which
is really all you need. Remember that even though the DMA controller
has its origins in ISA it is used elsewhere.

Note: x86_64 had a broken DMA API when it came to ISA but has since
been fixed. If your arch has problems then fix the DMA API instead of
reverting to the ISA functions.

Channels
--------

A normal ISA DMA controller has 8 channels. The lower four are for
8-bit transfers and the upper four are for 16-bit transfers.

Annotation

Implementation Notes