Back to home page

LXR

 
 

    


0001                         DMA with ISA and LPC devices
0002                         ============================
0003 
0004                       Pierre Ossman <drzeus@drzeus.cx>
0005 
0006 This document describes how to do DMA transfers using the old ISA DMA
0007 controller. Even though ISA is more or less dead today the LPC bus
0008 uses the same DMA system so it will be around for quite some time.
0009 
0010 Part I - Headers and dependencies
0011 ---------------------------------
0012 
0013 To do ISA style DMA you need to include two headers:
0014 
0015 #include <linux/dma-mapping.h>
0016 #include <asm/dma.h>
0017 
0018 The first is the generic DMA API used to convert virtual addresses to
0019 bus addresses (see Documentation/DMA-API.txt for details).
0020 
0021 The second contains the routines specific to ISA DMA transfers. Since
0022 this is not present on all platforms make sure you construct your
0023 Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
0024 to build your driver on unsupported platforms.
0025 
0026 Part II - Buffer allocation
0027 ---------------------------
0028 
0029 The ISA DMA controller has some very strict requirements on which
0030 memory it can access so extra care must be taken when allocating
0031 buffers.
0032 
0033 (You usually need a special buffer for DMA transfers instead of
0034 transferring directly to and from your normal data structures.)
0035 
0036 The DMA-able address space is the lowest 16 MB of _physical_ memory.
0037 Also the transfer block may not cross page boundaries (which are 64
0038 or 128 KiB depending on which channel you use).
0039 
0040 In order to allocate a piece of memory that satisfies all these
0041 requirements you pass the flag GFP_DMA to kmalloc.
0042 
0043 Unfortunately the memory available for ISA DMA is scarce so unless you
0044 allocate the memory during boot-up it's a good idea to also pass
0045 __GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.
0046 
0047 (This scarcity also means that you should allocate the buffer as
0048 early as possible and not release it until the driver is unloaded.)
0049 
0050 Part III - Address translation
0051 ------------------------------
0052 
0053 To translate the virtual address to a bus address, use the normal DMA
0054 API. Do _not_ use isa_virt_to_phys() even though it does the same
0055 thing. The reason for this is that the function isa_virt_to_phys()
0056 will require a Kconfig dependency to ISA, not just ISA_DMA_API which
0057 is really all you need. Remember that even though the DMA controller
0058 has its origins in ISA it is used elsewhere.
0059 
0060 Note: x86_64 had a broken DMA API when it came to ISA but has since
0061 been fixed. If your arch has problems then fix the DMA API instead of
0062 reverting to the ISA functions.
0063 
0064 Part IV - Channels
0065 ------------------
0066 
0067 A normal ISA DMA controller has 8 channels. The lower four are for
0068 8-bit transfers and the upper four are for 16-bit transfers.
0069 
0070 (Actually the DMA controller is really two separate controllers where
0071 channel 4 is used to give DMA access for the second controller (0-3).
0072 This means that of the four 16-bits channels only three are usable.)
0073 
0074 You allocate these in a similar fashion as all basic resources:
0075 
0076 extern int request_dma(unsigned int dmanr, const char * device_id);
0077 extern void free_dma(unsigned int dmanr);
0078 
0079 The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
0080 driver author but depends on what the hardware supports. Check your
0081 specs or test different channels.
0082 
0083 Part V - Transfer data
0084 ----------------------
0085 
0086 Now for the good stuff, the actual DMA transfer. :)
0087 
0088 Before you use any ISA DMA routines you need to claim the DMA lock
0089 using claim_dma_lock(). The reason is that some DMA operations are
0090 not atomic so only one driver may fiddle with the registers at a
0091 time.
0092 
0093 The first time you use the DMA controller you should call
0094 clear_dma_ff(). This clears an internal register in the DMA
0095 controller that is used for the non-atomic operations. As long as you
0096 (and everyone else) uses the locking functions then you only need to
0097 reset this once.
0098 
0099 Next, you tell the controller in which direction you intend to do the
0100 transfer using set_dma_mode(). Currently you have the options
0101 DMA_MODE_READ and DMA_MODE_WRITE.
0102 
0103 Set the address from where the transfer should start (this needs to
0104 be 16-bit aligned for 16-bit transfers) and how many bytes to
0105 transfer. Note that it's _bytes_. The DMA routines will do all the
0106 required translation to values that the DMA controller understands.
0107 
0108 The final step is enabling the DMA channel and releasing the DMA
0109 lock.
0110 
0111 Once the DMA transfer is finished (or timed out) you should disable
0112 the channel again. You should also check get_dma_residue() to make
0113 sure that all data has been transferred.
0114 
0115 Example:
0116 
0117 int flags, residue;
0118 
0119 flags = claim_dma_lock();
0120 
0121 clear_dma_ff();
0122 
0123 set_dma_mode(channel, DMA_MODE_WRITE);
0124 set_dma_addr(channel, phys_addr);
0125 set_dma_count(channel, num_bytes);
0126 
0127 dma_enable(channel);
0128 
0129 release_dma_lock(flags);
0130 
0131 while (!device_done());
0132 
0133 flags = claim_dma_lock();
0134 
0135 dma_disable(channel);
0136 
0137 residue = dma_get_residue(channel);
0138 if (residue != 0)
0139         printk(KERN_ERR "driver: Incomplete DMA transfer!"
0140                 " %d bytes left!\n", residue);
0141 
0142 release_dma_lock(flags);
0143 
0144 Part VI - Suspend/resume
0145 ------------------------
0146 
0147 It is the driver's responsibility to make sure that the machine isn't
0148 suspended while a DMA transfer is in progress. Also, all DMA settings
0149 are lost when the system suspends so if your driver relies on the DMA
0150 controller being in a certain state then you have to restore these
0151 registers upon resume.