Support functions for the SA11x0 internal DMA channels======================================================Nicolas Pitre <nico@cam.org>Last updated: 2001/07/15The DMA controller consists of six independent DMA channels. Each channelcan be configured to service any of the serial controllers. Two channelsare required to service a full-duplex serial controller. The DMAcontroller is intended to relieve the processor of the interrupt overheadin servicing these ports with programmed I/ O.If desired, any or all peripherals (except the UDC) may be serviced withprogrammed I/ O instead of DMA. Each peripheral is capable of requestingprocessor service through its own interrupt lines or through a DMArequest.A set of functions is provided to support drivers working with DMA buffersthrough a generic interface for (wishfully) all DMA usages.  Thosefunctions will take care of buffer queueing and splitting, DMA registermanagement, 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 channelnumber in '*channel'.  'device_id' should point to a string identifyingthe DMA usage or device (mainly for /proc).  'device' is the SA11x0peripheral's ports.  Note that reading from a port and writing to thesame port are actually considered as two different streams requiringtwo DMA channels with their own device type.  All possible dma_device_tare defined in include/asm-arm/arch-sa1100/dma.h.  If no channel isavailable, or if the desired device is already in use by another DMAchannel, then an error code is returned.  This function must be calledbefore 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 bufferwill be transmitted or filled with incoming data depending on the channelconfiguration made through sa1100_dma_set_device().  If the queue isempty, 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 asreturned by kmalloc() and friends.  The DMA controller must be given aphysical address to a buffer which is not cached bye the CPU data cache.To get such address, the DMA mapping functions (seeDocumentation/DMA-mapping.txt) are recommended.  The only relevantfunctions are pci_alloc_consistent(), pci_map_single() and their unmapcounterparts.  The PCI dev argument is NULL of course.There is no restriction on the buffer size.  The DMA code will split it upinternally to acommodate the DMA controller as needed.  If the buffercan'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 tonotify the driver which would have registered one.  The callback functionis prototyped as:void dma_callback( void *buf_id, int size );The 'buf_id' argument is the buffer identifier as passed tosa1100_dma_queue_buffer().  The 'size' argument is the number of bytes theDMA 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 complexprocessing to a bottom-half function or similar.  Allrestrictions 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 buffercurrently being processed.  If no such buffer is currently processed, anerror code is returned.  This is useful for mmap()'ed buffers like inaudio 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 throughsa1100_dma_stop().int sa1100_dma_flush_all( dmach_t channel );This completely flushes all queued buffers and on-going DMA transfers on agiven channel.  The next enqueued buffer following this call will beprocessed 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 receivesignal for its transmit clock reference, we need a mecanism to make theDMA "spin" on a certain buffer for when there is no more actual buffer toprocess.  The 'addr' argument is the physical memory address to use, andthe 'size' argument determines the spin DMA chunk.  This size can't belarger 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 isprocessed.  The spin buffer will only be reused when there is no moreacctual buffer to process.It is important not to choose a too small 'size' value since it willgreatly increase the interrupt load required to restart the spin.  Sincethis feature will typically be used on transmit DMAs, and because a bufferfull of zeros is probably the best thing to spin out, the 'addr' argumentmay well be used with FLUSH_BASE_PHYS for which no allocation nor memorybus 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 forfuture requests.Buffer allocation-----------------Like mentionned above, it is the driver's responsibility to allocate, freeand keep track of buffer space with dma_addr_t type addresses. However thedriver must not change the state of any buffer after it has been sent tosa1100-dma_queue_buffer().  When that function has been called, the bufferbecomes 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 inconjonction with the usage of pci_map_consistent() andsa1100_dma_get_current()... but then you must be sure you know what you'redoing (this doesn't work with pci_map_single()).Examples--------A real example of audio ring buffers is implemented in thedrivers/sound/sa1100-audio.c driver.  The SA1110 USB client and theSA11x0 FIR drivers are also using this interface to implement packetizedDMA.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 isnecessary to register the appropriate IRQ to be notified when the receiveris idle, the packet is complete, etc.  We could use one buffer at a timewith 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 forimprovements.TODO----- Create kernel-doc comments in the source to document the API and  let the documentation be generated automatically.