Support functions for the SA11x0 internal DMA channels ====================================================== Nicolas Pitre Last updated: 2001/07/15 The DMA controller consists of six independent DMA channels. Each channel can be configured to service any of the serial controllers. Two channels are required to service a full-duplex serial controller. The DMA controller is intended to relieve the processor of the interrupt overhead in servicing these ports with programmed I/ O. If desired, any or all peripherals (except the UDC) may be serviced with programmed I/ O instead of DMA. Each peripheral is capable of requesting processor service through its own interrupt lines or through a DMA request. A set of functions is provided to support drivers working with DMA buffers through a generic interface for (wishfully) all DMA usages. Those functions will take care of buffer queueing and splitting, DMA register management, interrupt handling, etc. SA11x0 DMA API -------------- Here is the description for the DMA API. int sa1100_request_dma( dmach_t *channel, const char *device_id, dma_device_t device ); This function will search for a free DMA channel and returns the channel number in '*channel'. 'device_id' should point to a string identifying the DMA usage or device (mainly for /proc). 'device' is the SA11x0 peripheral's ports. Note that reading from a port and writing to the same port are actually considered as two different streams requiring two DMA channels with their own device type. All possible dma_device_t are defined in include/asm-arm/arch-sa1100/dma.h. If no channel is available, or if the desired device is already in use by another DMA channel, then an error code is returned. This function must be called before any other DMA calls. int sa1100_dma_queue_buffer( dmach_t channel, void *buf_id, dma_addr_t data, int size ); This function enqueue the specified buffer for DMA processing. The buffer will be transmitted or filled with incoming data depending on the channel configuration made through sa1100_dma_set_device(). If the queue is empty, DMA starts immediately on the given buffer. Arguments are: dmach_t channel: the channel number. void *buf_id: a buffer identification known by the caller. dma_addr_t data: the buffer's physical address. int size: the buffer size in bytes. Note here the dma_addr_t which is not the same as the virtual address as returned by kmalloc() and friends. The DMA controller must be given a physical address to a buffer which is not cached bye the CPU data cache. To get such address, the DMA mapping functions (see Documentation/DMA-mapping.txt) are recommended. The only relevant functions are pci_alloc_consistent(), pci_map_single() and their unmap counterparts. The PCI dev argument is NULL of course. There is no restriction on the buffer size. The DMA code will split it up internally to acommodate the DMA controller as needed. If the buffer can't be enqueued the appropriate error code is returned. int sa1100_dma_set_callback( dmach_t channel, dma_callback_t cb ); As soon as the DMa completes with a buffer, a callback function is used to notify the driver which would have registered one. The callback function is prototyped as: void dma_callback( void *buf_id, int size ); The 'buf_id' argument is the buffer identifier as passed to sa1100_dma_queue_buffer(). The 'size' argument is the number of bytes the DMA processed (should be the same as the buffer size). Note that this callback function is called while in interrupt context. So it has to be small and efficient while posponing more complex processing to a bottom-half function or similar. All restrictions for interrupt handlers still apply. int sa1100_dma_get_current( dmach_t channel, void **buf_id, dma_addr_t *addr ); This returns the buffer ID and the DMA address pointer within the buffer currently being processed. If no such buffer is currently processed, an error code is returned. This is useful for mmap()'ed buffers like in audio drivers. int sa1100_dma_stop( dmach_t channel ); This call stops any DMA transfer on the given channel. int sa1100_dma_resume( dmach_t channel ); This call resumes a DMA transfer which would have been stopped through sa1100_dma_stop(). int sa1100_dma_flush_all( dmach_t channel ); This completely flushes all queued buffers and on-going DMA transfers on a given channel. The next enqueued buffer following this call will be processed right away. int sa1100_dma_set_spin( dmach_t channel, dma_addr_t addr, int size ); Because there is at least one device out there that uses its receive signal for its transmit clock reference, we need a mecanism to make the DMA "spin" on a certain buffer for when there is no more actual buffer to process. The 'addr' argument is the physical memory address to use, and the 'size' argument determines the spin DMA chunk. This size can't be larger than 8191 (if so, it is clamped to 4096). When the size is 0, the spin function is turned off. When activated, DMA will "spin" until there is any buffer in the queue. The current DMA chunk will terminate before a newly queued buffer is processed. The spin buffer will only be reused when there is no more acctual buffer to process. It is important not to choose a too small 'size' value since it will greatly increase the interrupt load required to restart the spin. Since this feature will typically be used on transmit DMAs, and because a buffer full of zeros is probably the best thing to spin out, the 'addr' argument may well be used with FLUSH_BASE_PHYS for which no allocation nor memory bus request are needed. The spinning DMA is affected by sa1100_dma_stop() and sa1100_dma_resume() but not bu sa1100_dma_flush_all(). void sa1100_free_dma( dmach_t channel ); This clears all activities on a given DMA channel and releases it for future requests. Buffer allocation ----------------- Like mentionned above, it is the driver's responsibility to allocate, free and keep track of buffer space with dma_addr_t type addresses. However the driver must not change the state of any buffer after it has been sent to sa1100-dma_queue_buffer(). When that function has been called, the buffer becomes the DMA's ownership until one of these events occur: - The callback function is called by the DMA code with a buffer ID to indicate that DMA processing terminated on that buffer. Then the driver owns the buffer again. - The sa1100-dma_flush_all() function is called by the driver at which point *all* queued buffers are owned by the driver again. - The sa1100-free_dma() does the same as sa1100-dma_flush_all(). This doesn't mean that you can't change the content of a queued buffer in conjonction with the usage of pci_map_consistent() and sa1100_dma_get_current()... but then you must be sure you know what you're doing (this doesn't work with pci_map_single()). Examples -------- A real example of audio ring buffers is implemented in the drivers/sound/sa1100-audio.c driver. The SA1110 USB client and the SA11x0 FIR drivers are also using this interface to implement packetized DMA. A transmit DMA for network packets could look like this (largely simplified): struct sk_buff *tx_ring_skb[RING_SIZE]; dma_addr_t tx_ring_dma[RING_SIZE]; int cur_tx; ... transmit function: tx_ring_skb[cur_tx] = skb; tx_ring_dma[cur_tx] = pci_map_single(NULL, skb->data, skb->len, PCI_DMA_TODEVICE); sa1100_dma_queue_buffer(channel, (void*)cur_tx, tx_ring_dma[cur_tx], skb->len); cur_tx++; cur_tx %= RING_SIZE; ... and the callback function: void tx_done_callback( void *buf_id, int size ) { int done_tx = (int) buf_id; struct sk_buff *skb = tx_ring_skb[done_tx]; pci_unmap_single(NULL, tx_ring_dma[done_tx], skb->len, PCI_DMA_TODEVICE); stats.tx_packets++; stats.tx_bytes += size; dev_kfree_skb_irq(skb); tx_ring_skb[done_tx] = NULL; } For drivers expecting variable length packets i.e. USB client, it is necessary to register the appropriate IRQ to be notified when the receiver is idle, the packet is complete, etc. We could use one buffer at a time with its ID being the virtual address of the buffer. Then the sequence: /* be sure DMA won't continue under our feet */ sa1100_dma_stop(channel); /* get the actual DMA length */ sa1100_get_current(channel, &data, &dma_ptr); /* acquire ownership for the buffer */ sa1100_dma_flush_all(channel); /* unmap the DMA buffer (actually doing cache coherency on ARM) */ pci_unmap_single (NULL, dma_addr, MAX_PKT_SIZE, PCI_DMA_FROMDEVICE); /* get remaining bytes from the fifo */ ptr = data + dma_ptr - dma_addr; while (fifo_not_empty) *ptr++ = get_byte_from_fifo; /* feed another free buffer for the next packet */ dma_addr2 = pci_map_single(NULL, data2, MAX_PKT_SIZE, PCI_DMA_FROMDEVICE); sa1100_dma_queue_buffer(channel, data2, dma_addr2, MAX_PKT_SIZE); /* process the current packet */ ... might do the trick. This looks a bit ugly but that's a starting point for improvements. TODO ---- - Create kernel-doc comments in the source to document the API and let the documentation be generated automatically.