blob: 8c2b8be6e45b9ac6104346a856e9b49b7f672cca [file] [log] [blame]
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -03001============================
2DMA with ISA and LPC devices
3============================
Pierre Ossmanddb99f32005-09-09 13:10:13 -07004
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -03005:Author: Pierre Ossman <drzeus@drzeus.cx>
Pierre Ossmanddb99f32005-09-09 13:10:13 -07006
7This document describes how to do DMA transfers using the old ISA DMA
8controller. Even though ISA is more or less dead today the LPC bus
9uses the same DMA system so it will be around for quite some time.
10
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030011Headers and dependencies
12------------------------
Pierre Ossmanddb99f32005-09-09 13:10:13 -070013
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030014To do ISA style DMA you need to include two headers::
Pierre Ossmanddb99f32005-09-09 13:10:13 -070015
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030016 #include <linux/dma-mapping.h>
17 #include <asm/dma.h>
Pierre Ossmanddb99f32005-09-09 13:10:13 -070018
19The first is the generic DMA API used to convert virtual addresses to
Bjorn Helgaas77f2ea22014-04-30 11:20:53 -060020bus addresses (see Documentation/DMA-API.txt for details).
Pierre Ossmanddb99f32005-09-09 13:10:13 -070021
22The second contains the routines specific to ISA DMA transfers. Since
23this is not present on all platforms make sure you construct your
24Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
25to build your driver on unsupported platforms.
26
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030027Buffer allocation
28-----------------
Pierre Ossmanddb99f32005-09-09 13:10:13 -070029
30The ISA DMA controller has some very strict requirements on which
31memory it can access so extra care must be taken when allocating
32buffers.
33
34(You usually need a special buffer for DMA transfers instead of
35transferring directly to and from your normal data structures.)
36
37The DMA-able address space is the lowest 16 MB of _physical_ memory.
38Also the transfer block may not cross page boundaries (which are 64
39or 128 KiB depending on which channel you use).
40
41In order to allocate a piece of memory that satisfies all these
42requirements you pass the flag GFP_DMA to kmalloc.
43
44Unfortunately the memory available for ISA DMA is scarce so unless you
45allocate the memory during boot-up it's a good idea to also pass
Michal Hockodcda9b02017-07-12 14:36:45 -070046__GFP_RETRY_MAYFAIL and __GFP_NOWARN to make the allocator try a bit harder.
Pierre Ossmanddb99f32005-09-09 13:10:13 -070047
48(This scarcity also means that you should allocate the buffer as
49early as possible and not release it until the driver is unloaded.)
50
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030051Address translation
52-------------------
Pierre Ossmanddb99f32005-09-09 13:10:13 -070053
Bjorn Helgaas77f2ea22014-04-30 11:20:53 -060054To translate the virtual address to a bus address, use the normal DMA
Pierre Ossmanddb99f32005-09-09 13:10:13 -070055API. Do _not_ use isa_virt_to_phys() even though it does the same
56thing. The reason for this is that the function isa_virt_to_phys()
57will require a Kconfig dependency to ISA, not just ISA_DMA_API which
58is really all you need. Remember that even though the DMA controller
59has its origins in ISA it is used elsewhere.
60
61Note: x86_64 had a broken DMA API when it came to ISA but has since
62been fixed. If your arch has problems then fix the DMA API instead of
63reverting to the ISA functions.
64
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030065Channels
66--------
Pierre Ossmanddb99f32005-09-09 13:10:13 -070067
68A normal ISA DMA controller has 8 channels. The lower four are for
698-bit transfers and the upper four are for 16-bit transfers.
70
71(Actually the DMA controller is really two separate controllers where
72channel 4 is used to give DMA access for the second controller (0-3).
73This means that of the four 16-bits channels only three are usable.)
74
75You allocate these in a similar fashion as all basic resources:
76
77extern int request_dma(unsigned int dmanr, const char * device_id);
78extern void free_dma(unsigned int dmanr);
79
80The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
81driver author but depends on what the hardware supports. Check your
82specs or test different channels.
83
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -030084Transfer data
85-------------
Pierre Ossmanddb99f32005-09-09 13:10:13 -070086
87Now for the good stuff, the actual DMA transfer. :)
88
89Before you use any ISA DMA routines you need to claim the DMA lock
90using claim_dma_lock(). The reason is that some DMA operations are
91not atomic so only one driver may fiddle with the registers at a
92time.
93
94The first time you use the DMA controller you should call
95clear_dma_ff(). This clears an internal register in the DMA
96controller that is used for the non-atomic operations. As long as you
97(and everyone else) uses the locking functions then you only need to
98reset this once.
99
100Next, you tell the controller in which direction you intend to do the
101transfer using set_dma_mode(). Currently you have the options
102DMA_MODE_READ and DMA_MODE_WRITE.
103
104Set the address from where the transfer should start (this needs to
105be 16-bit aligned for 16-bit transfers) and how many bytes to
106transfer. Note that it's _bytes_. The DMA routines will do all the
107required translation to values that the DMA controller understands.
108
109The final step is enabling the DMA channel and releasing the DMA
110lock.
111
112Once the DMA transfer is finished (or timed out) you should disable
113the channel again. You should also check get_dma_residue() to make
Matt LaPlantefa00e7e2006-11-30 04:55:36 +0100114sure that all data has been transferred.
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700115
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300116Example::
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700117
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300118 int flags, residue;
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700119
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300120 flags = claim_dma_lock();
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700121
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300122 clear_dma_ff();
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700123
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300124 set_dma_mode(channel, DMA_MODE_WRITE);
125 set_dma_addr(channel, phys_addr);
126 set_dma_count(channel, num_bytes);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700127
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300128 dma_enable(channel);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700129
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300130 release_dma_lock(flags);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700131
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300132 while (!device_done());
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700133
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300134 flags = claim_dma_lock();
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700135
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300136 dma_disable(channel);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700137
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300138 residue = dma_get_residue(channel);
139 if (residue != 0)
140 printk(KERN_ERR "driver: Incomplete DMA transfer!"
141 " %d bytes left!\n", residue);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700142
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300143 release_dma_lock(flags);
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700144
Mauro Carvalho Chehab5d75cf62017-05-14 13:16:36 -0300145Suspend/resume
146--------------
Pierre Ossmanddb99f32005-09-09 13:10:13 -0700147
148It is the driver's responsibility to make sure that the machine isn't
149suspended while a DMA transfer is in progress. Also, all DMA settings
150are lost when the system suspends so if your driver relies on the DMA
151controller being in a certain state then you have to restore these
152registers upon resume.