diff options
Diffstat (limited to 'board/xilinx/common/xdma_channel_sg.c')
| -rw-r--r-- | board/xilinx/common/xdma_channel_sg.c | 1317 |
1 files changed, 0 insertions, 1317 deletions
diff --git a/board/xilinx/common/xdma_channel_sg.c b/board/xilinx/common/xdma_channel_sg.c deleted file mode 100644 index a8e94625bf..0000000000 --- a/board/xilinx/common/xdma_channel_sg.c +++ /dev/null @@ -1,1317 +0,0 @@ -/* $Id: xdma_channel_sg.c,v 1.6 2003/02/03 19:50:33 moleres Exp $ */ -/****************************************************************************** -* -* Author: Xilinx, Inc. -* -* -* This program is free software; you can redistribute it and/or modify it -* under the terms of the GNU General Public License as published by the -* Free Software Foundation; either version 2 of the License, or (at your -* option) any later version. -* -* -* XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" AS A -* COURTESY TO YOU. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION AS -* ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD, -* XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE -* FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING -* ANY THIRD PARTY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION. -* XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO -* THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY -* WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM -* CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND -* FITNESS FOR A PARTICULAR PURPOSE. -* -* -* Xilinx hardware products are not intended for use in life support -* appliances, devices, or systems. Use in such applications is -* expressly prohibited. -* -* -* (c) Copyright 2002-2004 Xilinx Inc. -* All rights reserved. -* -* -* You should have received a copy of the GNU General Public License along -* with this program; if not, write to the Free Software Foundation, Inc., -* 675 Mass Ave, Cambridge, MA 02139, USA. -* -* FILENAME: -* -* xdma_channel_sg.c -* -* DESCRIPTION: -* -* This file contains the implementation of the XDmaChannel component which is -* related to scatter gather operations. -* -* Scatter Gather Operations -* -* The DMA channel may support scatter gather operations. A scatter gather -* operation automates the DMA channel such that multiple buffers can be -* sent or received with minimal software interaction with the hardware. Buffer -* descriptors, contained in the XBufDescriptor component, are used by the -* scatter gather operations of the DMA channel to describe the buffers to be -* processed. -* -* Scatter Gather List Operations -* -* A scatter gather list may be supported by each DMA channel. The scatter -* gather list allows buffer descriptors to be put into the list by a device -* driver which requires scatter gather. The hardware processes the buffer -* descriptors which are contained in the list and modifies the buffer -* descriptors to reflect the status of the DMA operations. The device driver -* is notified by interrupt that specific DMA events occur including scatter -* gather events. The device driver removes the completed buffer descriptors -* from the scatter gather list to evaluate the status of each DMA operation. -* -* The scatter gather list is created and buffer descriptors are inserted into -* the list. Buffer descriptors are never removed from the list after it's -* creation such that a put operation copies from a temporary buffer descriptor -* to a buffer descriptor in the list. Get operations don't copy from the list -* to a temporary, but return a pointer to the buffer descriptor in the list. -* A buffer descriptor in the list may be locked to prevent it from being -* overwritten by a put operation. This allows the device driver to get a -* descriptor from a scatter gather list and prevent it from being overwritten -* until the buffer associated with the buffer descriptor has been processed. -* -* The get and put functions only operate on the list and are asynchronous from -* the hardware which may be using the list of descriptors. This is important -* because there are no checks in the get and put functions to ensure that the -* hardware has processed the descriptors. This must be handled by the driver -* using the DMA scatter gather channel through the use of the other functions. -* When a scatter gather operation is started, the start function does ensure -* that the descriptor to start has not already been processed by the hardware -* and is not the first of a series of descriptors that have not been committed -* yet. -* -* Descriptors are put into the list but not marked as ready to use by the -* hardware until a commit operation is done. This allows multiple descriptors -* which may contain a single packet of information for a protocol to be -* guaranteed not to cause any underflow conditions during transmission. The -* hardware design only allows descriptors to cause it to stop after a descriptor -* has been processed rather than before it is processed. A series of -* descriptors are put into the list followed by a commit operation, or each -* descriptor may be commited. A commit operation is performed by changing a -* single descriptor, the first of the series of puts, to indicate that the -* hardware may now use all descriptors after it. The last descriptor in the -* list is always set to cause the hardware to stop after it is processed. -* -* Typical Scatter Gather Processing -* -* The following steps illustrate the typical processing to use the -* scatter gather features of a DMA channel. -* -* 1. Create a scatter gather list for the DMA channel which puts empty buffer -* descriptors into the list. -* 2. Create buffer descriptors which describe the buffers to be filled with -* receive data or the buffers which contain data to be sent. -* 3. Put buffer descriptors into the DMA channel scatter list such that scatter -* gather operations are requested. -* 4. Commit the buffer descriptors in the list such that they are ready to be -* used by the DMA channel hardware. -* 5. Start the scatter gather operations of the DMA channel. -* 6. Process any interrupts which occur as a result of the scatter gather -* operations or poll the DMA channel to determine the status. This may -* be accomplished by getting the packet count for the channel and then -* getting the appropriate number of descriptors from the list for that -* number of packets. -* -* Minimizing Interrupts -* -* The Scatter Gather operating mode is designed to reduce the amount of CPU -* throughput necessary to manage the hardware for devices. A key to the CPU -* throughput is the number and rate of interrupts that the CPU must service. -* Devices with higher data rates can cause larger numbers of interrupts and -* higher frequency interrupts. Ideally the number of interrupts can be reduced -* by only generating an interrupt when a specific amount of data has been -* received from the interface. This design suffers from a lack of interrupts -* when the amount of data received is less than the specified amount of data -* to generate an interrupt. In order to help minimize the number of interrupts -* which the CPU must service, an algorithm referred to as "interrupt coalescing" -* is utilized. -* -* Interrupt Coalescing -* -* The principle of interrupt coalescing is to wait before generating an -* interrupt until a certain number of packets have been received or sent. An -* interrupt is also generated if a smaller number of packets have been received -* followed by a certain period of time with no packet reception. This is a -* trade-off of latency for bandwidth and is accomplished using several -* mechanisms of the hardware including a counter for packets received or -* transmitted and a packet timer. These two hardware mechanisms work in -* combination to allow a reduction in the number of interrupts processed by the -* CPU for packet reception. -* -* Unserviced Packet Count -* -* The purpose of the packet counter is to count the number of packets received -* or transmitted and provide an interrupt when a specific number of packets -* have been processed by the hardware. An interrupt is generated whenever the -* counter is greater than or equal to the Packet Count Threshold. This counter -* contains an accurate count of the number of packets that the hardware has -* processed, either received or transmitted, and the software has not serviced. -* -* The packet counter allows the number of interrupts to be reduced by waiting -* to generate an interrupt until enough packets are received. For packet -* reception, packet counts of less than the number to generate an interrupt -* would not be serviced without the addition of a packet timer. This counter is -* continuously updated by the hardware, not latched to the value at the time -* the interrupt occurred. -* -* The packet counter can be used within the interrupt service routine for the -* device to reduce the number of interrupts. The interrupt service routine -* loops while performing processing for each packet which has been received or -* transmitted and decrements the counter by a specified value. At the same time, -* the hardware is possibly continuing to receive or transmit more packets such -* that the software may choose, based upon the value in the packet counter, to -* remain in the interrupt service routine rather than exiting and immediately -* returning. This feature should be used with caution as reducing the number of -* interrupts is beneficial, but unbounded interrupt processing is not desirable. -* -* Since the hardware may be incrementing the packet counter simultaneously -* with the software decrementing the counter, there is a need for atomic -* operations. The hardware ensures that the operation is atomic such that -* simultaneous accesses are properly handled. -* -* Packet Wait Bound -* -* The purpose of the packet wait bound is to augment the unserviced packet -* count. Whenever there is no pending interrupt for the channel and the -* unserviced packet count is non-zero, a timer starts counting timeout at the -* value contained the the packet wait bound register. If the timeout is -* reached, an interrupt is generated such that the software may service the -* data which was buffered. -* -* NOTES: -* -* Special Test Conditions: -* -* The scatter gather list processing must be thoroughly tested if changes are -* made. Testing should include putting and committing single descriptors and -* putting multiple descriptors followed by a single commit. There are some -* conditions in the code which handle the exception conditions. -* -* The Put Pointer points to the next location in the descriptor list to copy -* in a new descriptor. The Get Pointer points to the next location in the -* list to get a descriptor from. The Get Pointer only allows software to -* have a traverse the list after the hardware has finished processing some -* number of descriptors. The Commit Pointer points to the descriptor in the -* list which is to be committed. It is also used to determine that no -* descriptor is waiting to be commited (NULL). The Last Pointer points to -* the last descriptor that was put into the list. It typically points -* to the previous descriptor to the one pointed to by the Put Pointer. -* Comparisons are done between these pointers to determine when the following -* special conditions exist. - -* Single Put And Commit -* -* The buffer descriptor is ready to be used by the hardware so it is important -* for the descriptor to not appear to be waiting to be committed. The commit -* pointer is reset when a commit is done indicating there are no descriptors -* waiting to be committed. In all cases but this one, the descriptor is -* changed to cause the hardware to go to the next descriptor after processing -* this one. But in this case, this is the last descriptor in the list such -* that it must not be changed. -* -* 3 Or More Puts And Commit -* -* A series of 3 or more puts followed by a single commit is different in that -* only the 1st descriptor put into the list is changed when the commit is done. -* This requires each put starting on the 3rd to change the previous descriptor -* so that it allows the hardware to continue to the next descriptor in the list. -* -* The 1st Put Following A Commit -* -* The commit caused the commit pointer to be NULL indicating that there are no -* descriptors waiting to be committed. It is necessary for the next put to set -* the commit pointer so that a commit must follow the put for the hardware to -* use the descriptor. -* -* <pre> -* MODIFICATION HISTORY: -* -* Ver Who Date Changes -* ----- ---- -------- ------------------------------------------------------ -* 1.00a rpm 02/03/03 Removed the XST_DMA_SG_COUNT_EXCEEDED return code -* from SetPktThreshold. -* </pre> -* -******************************************************************************/ - -/***************************** Include Files *********************************/ - -#include "xdma_channel.h" -#include "xbasic_types.h" -#include "xio.h" -#include "xbuf_descriptor.h" -#include "xstatus.h" - -/************************** Constant Definitions *****************************/ - -#define XDC_SWCR_SG_ENABLE_MASK 0x80000000UL /* scatter gather enable */ - -/**************************** Type Definitions *******************************/ - -/***************** Macros (Inline Functions) Definitions *********************/ - -/* the following macro copies selected fields of a buffer descriptor to another - * buffer descriptor, this was provided by the buffer descriptor component but - * was moved here since it is only used internally to this component and since - * it does not copy all fields - */ -#define CopyBufferDescriptor(InstancePtr, DestinationPtr) \ -{ \ - *((u32 *)DestinationPtr + XBD_CONTROL_OFFSET) = \ - *((u32 *)InstancePtr + XBD_CONTROL_OFFSET); \ - *((u32 *)DestinationPtr + XBD_SOURCE_OFFSET) = \ - *((u32 *)InstancePtr + XBD_SOURCE_OFFSET); \ - *((u32 *)DestinationPtr + XBD_DESTINATION_OFFSET) = \ - *((u32 *)InstancePtr + XBD_DESTINATION_OFFSET); \ - *((u32 *)DestinationPtr + XBD_LENGTH_OFFSET) = \ - *((u32 *)InstancePtr + XBD_LENGTH_OFFSET); \ - *((u32 *)DestinationPtr + XBD_STATUS_OFFSET) = \ - *((u32 *)InstancePtr + XBD_STATUS_OFFSET); \ - *((u32 *)DestinationPtr + XBD_DEVICE_STATUS_OFFSET) = \ - *((u32 *)InstancePtr + XBD_DEVICE_STATUS_OFFSET); \ - *((u32 *)DestinationPtr + XBD_ID_OFFSET) = \ - *((u32 *)InstancePtr + XBD_ID_OFFSET); \ - *((u32 *)DestinationPtr + XBD_FLAGS_OFFSET) = \ - *((u32 *)InstancePtr + XBD_FLAGS_OFFSET); \ - *((u32 *)DestinationPtr + XBD_RQSTED_LENGTH_OFFSET) = \ - *((u32 *)InstancePtr + XBD_RQSTED_LENGTH_OFFSET); \ -} - -/************************** Variable Definitions *****************************/ - -/************************** Function Prototypes ******************************/ - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_SgStart -* -* DESCRIPTION: -* -* This function starts a scatter gather operation for a scatter gather -* DMA channel. The first buffer descriptor in the buffer descriptor list -* will be started with the scatter gather operation. A scatter gather list -* should have previously been created for the DMA channel and buffer -* descriptors put into the scatter gather list such that there are scatter -* operations ready to be performed. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* A status containing XST_SUCCESS if scatter gather was started successfully -* for the DMA channel. -* -* A value of XST_DMA_SG_NO_LIST indicates the scatter gather list has not -* been created. -* -* A value of XST_DMA_SG_LIST_EMPTY indicates scatter gather was not started -* because the scatter gather list of the DMA channel does not contain any -* buffer descriptors that are ready to be processed by the hardware. -* -* A value of XST_DMA_SG_IS_STARTED indicates scatter gather was not started -* because the scatter gather was not stopped, but was already started. -* -* A value of XST_DMA_SG_BD_NOT_COMMITTED indicates the buffer descriptor of -* scatter gather list which was to be started is not committed to the list. -* This status is more likely if this function is being called from an ISR -* and non-ISR processing is putting descriptors into the list. -* -* A value of XST_DMA_SG_NO_DATA indicates that the buffer descriptor of the -* scatter gather list which was to be started had already been used by the -* hardware for a DMA transfer that has been completed. -* -* NOTES: -* -* It is the responsibility of the caller to get all the buffer descriptors -* after performing a stop operation and before performing a start operation. -* If buffer descriptors are not retrieved between stop and start operations, -* buffer descriptors may be processed by the hardware more than once. -* -******************************************************************************/ -XStatus -XDmaChannel_SgStart(XDmaChannel * InstancePtr) -{ - u32 Register; - XBufDescriptor *LastDescriptorPtr; - - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if a scatter gather list has not been created yet, return a status */ - - if (InstancePtr->TotalDescriptorCount == 0) { - return XST_DMA_SG_NO_LIST; - } - - /* if the scatter gather list exists but is empty then return a status */ - - if (XDmaChannel_IsSgListEmpty(InstancePtr)) { - return XST_DMA_SG_LIST_EMPTY; - } - - /* if scatter gather is busy for the DMA channel, return a status because - * restarting it could lose data - */ - - Register = XIo_In32(InstancePtr->RegBaseAddress + XDC_DMAS_REG_OFFSET); - if (Register & XDC_DMASR_SG_BUSY_MASK) { - return XST_DMA_SG_IS_STARTED; - } - - /* get the address of the last buffer descriptor which the DMA hardware - * finished processing - */ - LastDescriptorPtr = - (XBufDescriptor *) XIo_In32(InstancePtr->RegBaseAddress + - XDC_BDA_REG_OFFSET); - - /* setup the first buffer descriptor that will be sent when the scatter - * gather channel is enabled, this is only necessary one time since - * the BDA register of the channel maintains the last buffer descriptor - * processed - */ - if (LastDescriptorPtr == NULL) { - XIo_Out32(InstancePtr->RegBaseAddress + XDC_BDA_REG_OFFSET, - (u32) InstancePtr->GetPtr); - } else { - XBufDescriptor *NextDescriptorPtr; - - /* get the next descriptor to be started, if the status indicates it - * hasn't already been used by the h/w, then it's OK to start it, - * s/w sets the status of each descriptor to busy and then h/w clears - * the busy when it is complete - */ - NextDescriptorPtr = - XBufDescriptor_GetNextPtr(LastDescriptorPtr); - - if ((XBufDescriptor_GetStatus(NextDescriptorPtr) & - XDC_DMASR_BUSY_MASK) == 0) { - return XST_DMA_SG_NO_DATA; - } - /* don't start the DMA SG channel if the descriptor to be processed - * by h/w is to be committed by the s/w, this function can be called - * such that it interrupts a thread that was putting into the list - */ - if (NextDescriptorPtr == InstancePtr->CommitPtr) { - return XST_DMA_SG_BD_NOT_COMMITTED; - } - } - - /* start the scatter gather operation by clearing the stop bit in the - * control register and setting the enable bit in the s/w control register, - * both of these are necessary to cause it to start, right now the order of - * these statements is important, the software control register should be - * set 1st. The other order can cause the CPU to have a loss of sync - * because it cannot read/write the register while the DMA operation is - * running - */ - - Register = XIo_In32(InstancePtr->RegBaseAddress + XDC_SWCR_REG_OFFSET); - - XIo_Out32(InstancePtr->RegBaseAddress + XDC_SWCR_REG_OFFSET, - Register | XDC_SWCR_SG_ENABLE_MASK); - - Register = XIo_In32(InstancePtr->RegBaseAddress + XDC_DMAC_REG_OFFSET); - - XIo_Out32(InstancePtr->RegBaseAddress + XDC_DMAC_REG_OFFSET, - Register & ~XDC_DMACR_SG_DISABLE_MASK); - - /* indicate the DMA channel scatter gather operation was started - * successfully - */ - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_SgStop -* -* DESCRIPTION: -* -* This function stops a scatter gather operation for a scatter gather -* DMA channel. This function starts the process of stopping a scatter -* gather operation that is in progress and waits for the stop to be completed. -* Since it waits for the operation to stopped before returning, this function -* could take an amount of time relative to the size of the DMA scatter gather -* operation which is in progress. The scatter gather list of the DMA channel -* is not modified by this function such that starting the scatter gather -* channel after stopping it will cause it to resume. This operation is -* considered to be a graceful stop in that the scatter gather operation -* completes the current buffer descriptor before stopping. -* -* If the interrupt is enabled, an interrupt will be generated when the -* operation is stopped and the caller is responsible for handling the -* interrupt. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* BufDescriptorPtr is also a return value which contains a pointer to the -* buffer descriptor which the scatter gather operation completed when it -* was stopped. -* -* RETURN VALUE: -* -* A status containing XST_SUCCESS if scatter gather was stopped successfully -* for the DMA channel. -* -* A value of XST_DMA_SG_IS_STOPPED indicates scatter gather was not stoppped -* because the scatter gather is not started, but was already stopped. -* -* BufDescriptorPtr contains a pointer to the buffer descriptor which was -* completed when the operation was stopped. -* -* NOTES: -* -* This function implements a loop which polls the hardware for an infinite -* amount of time. If the hardware is not operating correctly, this function -* may never return. -* -******************************************************************************/ -XStatus -XDmaChannel_SgStop(XDmaChannel * InstancePtr, - XBufDescriptor ** BufDescriptorPtr) -{ - u32 Register; - - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(BufDescriptorPtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* get the contents of the software control register, if scatter gather is not - * enabled (started), then return a status because the disable acknowledge - * would not be generated - */ - Register = XIo_In32(InstancePtr->RegBaseAddress + XDC_SWCR_REG_OFFSET); - - if ((Register & XDC_SWCR_SG_ENABLE_MASK) == 0) { - return XST_DMA_SG_IS_STOPPED; - } - - /* Ensure the interrupt status for the scatter gather is cleared such - * that this function will wait til the disable has occurred, writing - * a 1 to only that bit in the register will clear only it - */ - XIo_Out32(InstancePtr->RegBaseAddress + XDC_IS_REG_OFFSET, - XDC_IXR_SG_DISABLE_ACK_MASK); - - /* disable scatter gather by writing to the software control register - * without modifying any other bits of the register - */ - XIo_Out32(InstancePtr->RegBaseAddress + XDC_SWCR_REG_OFFSET, - Register & ~XDC_SWCR_SG_ENABLE_MASK); - - /* scatter gather does not disable immediately, but after the current - * buffer descriptor is complete, so wait for the DMA channel to indicate - * the disable is complete - */ - do { - Register = - XIo_In32(InstancePtr->RegBaseAddress + XDC_IS_REG_OFFSET); - } while ((Register & XDC_IXR_SG_DISABLE_ACK_MASK) == 0); - - /* Ensure the interrupt status for the scatter gather disable is cleared, - * writing a 1 to only that bit in the register will clear only it - */ - XIo_Out32(InstancePtr->RegBaseAddress + XDC_IS_REG_OFFSET, - XDC_IXR_SG_DISABLE_ACK_MASK); - - /* set the specified buffer descriptor pointer to point to the buffer - * descriptor that the scatter gather DMA channel was processing - */ - *BufDescriptorPtr = - (XBufDescriptor *) XIo_In32(InstancePtr->RegBaseAddress + - XDC_BDA_REG_OFFSET); - - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_CreateSgList -* -* DESCRIPTION: -* -* This function creates a scatter gather list in the DMA channel. A scatter -* gather list consists of a list of buffer descriptors that are available to -* be used for scatter gather operations. Buffer descriptors are put into the -* list to request a scatter gather operation to be performed. -* -* A number of buffer descriptors are created from the specified memory and put -* into a buffer descriptor list as empty buffer descriptors. This function must -* be called before non-empty buffer descriptors may be put into the DMA channel -* to request scatter gather operations. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* MemoryPtr contains a pointer to the memory which is to be used for buffer -* descriptors and must not be cached. -* -* ByteCount contains the number of bytes for the specified memory to be used -* for buffer descriptors. -* -* RETURN VALUE: -* -* A status contains XST_SUCCESS if the scatter gather list was successfully -* created. -* -* A value of XST_DMA_SG_LIST_EXISTS indicates that the scatter gather list -* was not created because the list has already been created. -* -* NOTES: -* -* None. -* -******************************************************************************/ -XStatus -XDmaChannel_CreateSgList(XDmaChannel * InstancePtr, - u32 * MemoryPtr, u32 ByteCount) -{ - XBufDescriptor *BufferDescriptorPtr = (XBufDescriptor *) MemoryPtr; - XBufDescriptor *PreviousDescriptorPtr = NULL; - XBufDescriptor *StartOfListPtr = BufferDescriptorPtr; - u32 UsedByteCount; - - /* assert to verify valid input arguments, alignment for those - * arguments that have alignment restrictions, and at least enough - * memory for one buffer descriptor - */ - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(MemoryPtr != NULL); - XASSERT_NONVOID(((u32) MemoryPtr & 3) == 0); - XASSERT_NONVOID(ByteCount != 0); - XASSERT_NONVOID(ByteCount >= sizeof (XBufDescriptor)); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if the scatter gather list has already been created, then return - * with a status - */ - if (InstancePtr->TotalDescriptorCount != 0) { - return XST_DMA_SG_LIST_EXISTS; - } - - /* loop thru the specified memory block and create as many buffer - * descriptors as possible putting each into the list which is - * implemented as a ring buffer, make sure not to use any memory which - * is not large enough for a complete buffer descriptor - */ - UsedByteCount = 0; - while ((UsedByteCount + sizeof (XBufDescriptor)) <= ByteCount) { - /* setup a pointer to the next buffer descriptor in the memory and - * update # of used bytes to know when all of memory is used - */ - BufferDescriptorPtr = (XBufDescriptor *) ((u32) MemoryPtr + - UsedByteCount); - - /* initialize the new buffer descriptor such that it doesn't contain - * garbage which could be used by the DMA hardware - */ - XBufDescriptor_Initialize(BufferDescriptorPtr); - - /* if this is not the first buffer descriptor to be created, - * then link it to the last created buffer descriptor - */ - if (PreviousDescriptorPtr != NULL) { - XBufDescriptor_SetNextPtr(PreviousDescriptorPtr, - BufferDescriptorPtr); - } - - /* always keep a pointer to the last created buffer descriptor such - * that they can be linked together in the ring buffer - */ - PreviousDescriptorPtr = BufferDescriptorPtr; - - /* keep a count of the number of descriptors in the list to allow - * error processing to be performed - */ - InstancePtr->TotalDescriptorCount++; - - UsedByteCount += sizeof (XBufDescriptor); - } - - /* connect the last buffer descriptor created and inserted in the list - * to the first such that a ring buffer is created - */ - XBufDescriptor_SetNextPtr(BufferDescriptorPtr, StartOfListPtr); - - /* initialize the ring buffer to indicate that there are no - * buffer descriptors in the list which point to valid data buffers - */ - InstancePtr->PutPtr = BufferDescriptorPtr; - InstancePtr->GetPtr = BufferDescriptorPtr; - InstancePtr->CommitPtr = NULL; - InstancePtr->LastPtr = BufferDescriptorPtr; - InstancePtr->ActiveDescriptorCount = 0; - - /* indicate the scatter gather list was successfully created */ - - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_IsSgListEmpty -* -* DESCRIPTION: -* -* This function determines if the scatter gather list of a DMA channel is -* empty with regard to buffer descriptors which are pointing to buffers to be -* used for scatter gather operations. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* A value of TRUE if the scatter gather list is empty, otherwise a value of -* FALSE. -* -* NOTES: -* -* None. -* -******************************************************************************/ -u32 -XDmaChannel_IsSgListEmpty(XDmaChannel * InstancePtr) -{ - /* assert to verify valid input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if the number of descriptors which are being used in the list is zero - * then the list is empty - */ - return (InstancePtr->ActiveDescriptorCount == 0); -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_PutDescriptor -* -* DESCRIPTION: -* -* This function puts a buffer descriptor into the DMA channel scatter -* gather list. A DMA channel maintains a list of buffer descriptors which are -* to be processed. This function puts the specified buffer descriptor -* at the next location in the list. Note that since the list is already intact, -* the information in the parameter is copied into the list (rather than modify -* list pointers on the fly). -* -* After buffer descriptors are put into the list, they must also be committed -* by calling another function. This allows multiple buffer descriptors which -* span a single packet to be put into the list while preventing the hardware -* from starting the first buffer descriptor of the packet. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* BufferDescriptorPtr is a pointer to the buffer descriptor to be put into -* the next available location of the scatter gather list. -* -* RETURN VALUE: -* -* A status which indicates XST_SUCCESS if the buffer descriptor was -* successfully put into the scatter gather list. -* -* A value of XST_DMA_SG_NO_LIST indicates the scatter gather list has not -* been created. -* -* A value of XST_DMA_SG_LIST_FULL indicates the buffer descriptor was not -* put into the list because the list was full. -* -* A value of XST_DMA_SG_BD_LOCKED indicates the buffer descriptor was not -* put into the list because the buffer descriptor in the list which is to -* be overwritten was locked. A locked buffer descriptor indicates the higher -* layered software is still using the buffer descriptor. -* -* NOTES: -* -* It is necessary to create a scatter gather list for a DMA channel before -* putting buffer descriptors into it. -* -******************************************************************************/ -XStatus -XDmaChannel_PutDescriptor(XDmaChannel * InstancePtr, - XBufDescriptor * BufferDescriptorPtr) -{ - u32 Control; - - /* assert to verify valid input arguments and alignment for those - * arguments that have alignment restrictions - */ - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(BufferDescriptorPtr != NULL); - XASSERT_NONVOID(((u32) BufferDescriptorPtr & 3) == 0); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if a scatter gather list has not been created yet, return a status */ - - if (InstancePtr->TotalDescriptorCount == 0) { - return XST_DMA_SG_NO_LIST; - } - - /* if the list is full because all descriptors are pointing to valid - * buffers, then indicate an error, this code assumes no list or an - * empty list is detected above - */ - if (InstancePtr->ActiveDescriptorCount == - InstancePtr->TotalDescriptorCount) { - return XST_DMA_SG_LIST_FULL; - } - - /* if the buffer descriptor in the list which is to be overwritten is - * locked, then don't overwrite it and return a status - */ - if (XBufDescriptor_IsLocked(InstancePtr->PutPtr)) { - return XST_DMA_SG_BD_LOCKED; - } - - /* set the scatter gather stop bit in the control word of the descriptor - * to cause the h/w to stop after it processes this descriptor since it - * will be the last in the list - */ - Control = XBufDescriptor_GetControl(BufferDescriptorPtr); - XBufDescriptor_SetControl(BufferDescriptorPtr, - Control | XDC_DMACR_SG_DISABLE_MASK); - - /* set both statuses in the descriptor so we tell if they are updated with - * the status of the transfer, the hardware should change the busy in the - * DMA status to be false when it completes - */ - XBufDescriptor_SetStatus(BufferDescriptorPtr, XDC_DMASR_BUSY_MASK); - XBufDescriptor_SetDeviceStatus(BufferDescriptorPtr, 0); - - /* copy the descriptor into the next position in the list so it's ready to - * be used by the h/w, this assumes the descriptor in the list prior to this - * one still has the stop bit in the control word set such that the h/w - * use this one yet - */ - CopyBufferDescriptor(BufferDescriptorPtr, InstancePtr->PutPtr); - - /* only the last in the list and the one to be committed have scatter gather - * disabled in the control word, a commit requires only one descriptor - * to be changed, when # of descriptors to commit > 2 all others except the - * 1st and last have scatter gather enabled - */ - if ((InstancePtr->CommitPtr != InstancePtr->LastPtr) && - (InstancePtr->CommitPtr != NULL)) { - Control = XBufDescriptor_GetControl(InstancePtr->LastPtr); - XBufDescriptor_SetControl(InstancePtr->LastPtr, - Control & ~XDC_DMACR_SG_DISABLE_MASK); - } - - /* update the list data based upon putting a descriptor into the list, - * these operations must be last - */ - InstancePtr->ActiveDescriptorCount++; - - /* only update the commit pointer if it is not already active, this allows - * it to be deactivated after every commit such that a single descriptor - * which is committed does not appear to be waiting to be committed - */ - if (InstancePtr->CommitPtr == NULL) { - InstancePtr->CommitPtr = InstancePtr->LastPtr; - } - - /* these updates MUST BE LAST after the commit pointer update in order for - * the commit pointer to track the correct descriptor to be committed - */ - InstancePtr->LastPtr = InstancePtr->PutPtr; - InstancePtr->PutPtr = XBufDescriptor_GetNextPtr(InstancePtr->PutPtr); - - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_CommitPuts -* -* DESCRIPTION: -* -* This function commits the buffer descriptors which have been put into the -* scatter list for the DMA channel since the last commit operation was -* performed. This enables the calling functions to put several buffer -* descriptors into the list (e.g.,a packet's worth) before allowing the scatter -* gather operations to start. This prevents the DMA channel hardware from -* starting to use the buffer descriptors in the list before they are ready -* to be used (multiple buffer descriptors for a single packet). -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* A status indicating XST_SUCCESS if the buffer descriptors of the list were -* successfully committed. -* -* A value of XST_DMA_SG_NOTHING_TO_COMMIT indicates that the buffer descriptors -* were not committed because there was nothing to commit in the list. All the -* buffer descriptors which are in the list are commited. -* -* NOTES: -* -* None. -* -******************************************************************************/ -XStatus -XDmaChannel_CommitPuts(XDmaChannel * InstancePtr) -{ - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if the buffer descriptor to be committed is already committed or - * the list is empty (none have been put in), then indicate an error - */ - if ((InstancePtr->CommitPtr == NULL) || - XDmaChannel_IsSgListEmpty(InstancePtr)) { - return XST_DMA_SG_NOTHING_TO_COMMIT; - } - - /* last descriptor in the list must have scatter gather disabled so the end - * of the list is hit by h/w, if descriptor to commit is not last in list, - * commit descriptors by enabling scatter gather in the descriptor - */ - if (InstancePtr->CommitPtr != InstancePtr->LastPtr) { - u32 Control; - - Control = XBufDescriptor_GetControl(InstancePtr->CommitPtr); - XBufDescriptor_SetControl(InstancePtr->CommitPtr, Control & - ~XDC_DMACR_SG_DISABLE_MASK); - } - /* Update the commit pointer to indicate that there is nothing to be - * committed, this state is used by start processing to know that the - * buffer descriptor to start is not waiting to be committed - */ - InstancePtr->CommitPtr = NULL; - - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_GetDescriptor -* -* DESCRIPTION: -* -* This function gets a buffer descriptor from the scatter gather list of the -* DMA channel. The buffer descriptor is retrieved from the scatter gather list -* and the scatter gather list is updated to not include the retrieved buffer -* descriptor. This is typically done after a scatter gather operation -* completes indicating that a data buffer has been successfully sent or data -* has been received into the data buffer. The purpose of this function is to -* allow the device using the scatter gather operation to get the results of the -* operation. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* BufDescriptorPtr is a pointer to a pointer to the buffer descriptor which -* was retrieved from the list. The buffer descriptor is not really removed -* from the list, but it is changed to a state such that the hardware will not -* use it again until it is put into the scatter gather list of the DMA channel. -* -* RETURN VALUE: -* -* A status indicating XST_SUCCESS if a buffer descriptor was retrieved from -* the scatter gather list of the DMA channel. -* -* A value of XST_DMA_SG_NO_LIST indicates the scatter gather list has not -* been created. -* -* A value of XST_DMA_SG_LIST_EMPTY indicates no buffer descriptor was -* retrieved from the list because there are no buffer descriptors to be -* processed in the list. -* -* BufDescriptorPtr is updated to point to the buffer descriptor which was -* retrieved from the list if the status indicates success. -* -* NOTES: -* -* None. -* -******************************************************************************/ -XStatus -XDmaChannel_GetDescriptor(XDmaChannel * InstancePtr, - XBufDescriptor ** BufDescriptorPtr) -{ - u32 Control; - - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(BufDescriptorPtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if a scatter gather list has not been created yet, return a status */ - - if (InstancePtr->TotalDescriptorCount == 0) { - return XST_DMA_SG_NO_LIST; - } - - /* if the buffer descriptor list is empty, then indicate an error */ - - if (XDmaChannel_IsSgListEmpty(InstancePtr)) { - return XST_DMA_SG_LIST_EMPTY; - } - - /* retrieve the next buffer descriptor which is ready to be processed from - * the buffer descriptor list for the DMA channel, set the control word - * such that hardware will stop after the descriptor has been processed - */ - Control = XBufDescriptor_GetControl(InstancePtr->GetPtr); - XBufDescriptor_SetControl(InstancePtr->GetPtr, - Control | XDC_DMACR_SG_DISABLE_MASK); - - /* set the input argument, which is also an output, to point to the - * buffer descriptor which is to be retrieved from the list - */ - *BufDescriptorPtr = InstancePtr->GetPtr; - - /* update the pointer of the DMA channel to reflect the buffer descriptor - * was retrieved from the list by setting it to the next buffer descriptor - * in the list and indicate one less descriptor in the list now - */ - InstancePtr->GetPtr = XBufDescriptor_GetNextPtr(InstancePtr->GetPtr); - InstancePtr->ActiveDescriptorCount--; - - return XST_SUCCESS; -} - -/*********************** Interrupt Collescing Functions **********************/ - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_GetPktCount -* -* DESCRIPTION: -* -* This function returns the value of the unserviced packet count register of -* the DMA channel. This count represents the number of packets that have been -* sent or received by the hardware, but not processed by software. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* The unserviced packet counter register contents for the DMA channel. -* -* NOTES: -* -* None. -* -******************************************************************************/ -u32 -XDmaChannel_GetPktCount(XDmaChannel * InstancePtr) -{ - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* get the unserviced packet count from the register and return it */ - - return XIo_In32(InstancePtr->RegBaseAddress + XDC_UPC_REG_OFFSET); -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_DecrementPktCount -* -* DESCRIPTION: -* -* This function decrements the value of the unserviced packet count register. -* This informs the hardware that the software has processed a packet. The -* unserviced packet count register may only be decremented by one in the -* hardware. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* None. -* -* NOTES: -* -* None. -* -******************************************************************************/ -void -XDmaChannel_DecrementPktCount(XDmaChannel * InstancePtr) -{ - u32 Register; - - /* assert to verify input arguments */ - - XASSERT_VOID(InstancePtr != NULL); - XASSERT_VOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* if the unserviced packet count register can be decremented (rather - * than rolling over) decrement it by writing a 1 to the register, - * this is the only valid write to the register as it serves as an - * acknowledge that a packet was handled by the software - */ - Register = XIo_In32(InstancePtr->RegBaseAddress + XDC_UPC_REG_OFFSET); - if (Register > 0) { - XIo_Out32(InstancePtr->RegBaseAddress + XDC_UPC_REG_OFFSET, - 1UL); - } -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_SetPktThreshold -* -* DESCRIPTION: -* -* This function sets the value of the packet count threshold register of the -* DMA channel. It reflects the number of packets that must be sent or -* received before generating an interrupt. This value helps implement -* a concept called "interrupt coalescing", which is used to reduce the number -* of interrupts from devices with high data rates. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* Threshold is the value that is written to the threshold register of the -* DMA channel. -* -* RETURN VALUE: -* -* A status containing XST_SUCCESS if the packet count threshold was -* successfully set. -* -* NOTES: -* -* The packet threshold could be set to larger than the number of descriptors -* allocated to the DMA channel. In this case, the wait bound will take over -* and always indicate data arrival. There was a check in this function that -* returned an error if the treshold was larger than the number of descriptors, -* but that was removed because users would then have to set the threshold -* only after they set descriptor space, which is an order dependency that -* caused confustion. -* -******************************************************************************/ -XStatus -XDmaChannel_SetPktThreshold(XDmaChannel * InstancePtr, u8 Threshold) -{ - /* assert to verify input arguments, don't assert the threshold since - * it's range is unknown - */ - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* set the packet count threshold in the register such that an interrupt - * may be generated, if enabled, when the packet count threshold is - * reached or exceeded - */ - XIo_Out32(InstancePtr->RegBaseAddress + XDC_PCT_REG_OFFSET, - (u32) Threshold); - - /* indicate the packet count threshold was successfully set */ - - return XST_SUCCESS; -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_GetPktThreshold -* -* DESCRIPTION: -* -* This function gets the value of the packet count threshold register of the -* DMA channel. This value reflects the number of packets that must be sent or -* received before generating an interrupt. This value helps implement a concept -* called "interrupt coalescing", which is used to reduce the number of -* interrupts from devices with high data rates. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* The packet threshold register contents for the DMA channel and is a value in -* the range 0 - 1023. A value of 0 indicates the packet wait bound timer is -* disabled. -* -* NOTES: -* -* None. -* -******************************************************************************/ -u8 -XDmaChannel_GetPktThreshold(XDmaChannel * InstancePtr) -{ - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* get the packet count threshold from the register and return it, - * since only 8 bits are used, cast it to return only those bits */ - - return (u8) XIo_In32(InstancePtr->RegBaseAddress + XDC_PCT_REG_OFFSET); -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_SetPktWaitBound -* -* DESCRIPTION: -* -* This function sets the value of the packet wait bound register of the -* DMA channel. This value reflects the timer value used to trigger an -* interrupt when not enough packets have been received to reach the packet -* count threshold. -* -* The timer is in millisecond units with +/- 33% accuracy. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* WaitBound is the value, in milliseconds, to be stored in the wait bound -* register of the DMA channel and is a value in the range 0 - 1023. A value -* of 0 disables the packet wait bound timer. -* -* RETURN VALUE: -* -* None. -* -* NOTES: -* -* None. -* -******************************************************************************/ -void -XDmaChannel_SetPktWaitBound(XDmaChannel * InstancePtr, u32 WaitBound) -{ - /* assert to verify input arguments */ - - XASSERT_VOID(InstancePtr != NULL); - XASSERT_VOID(WaitBound < 1024); - XASSERT_VOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* set the packet wait bound in the register such that interrupt may be - * generated, if enabled, when packets have not been handled for a specific - * amount of time - */ - XIo_Out32(InstancePtr->RegBaseAddress + XDC_PWB_REG_OFFSET, WaitBound); -} - -/****************************************************************************** -* -* FUNCTION: -* -* XDmaChannel_GetPktWaitBound -* -* DESCRIPTION: -* -* This function gets the value of the packet wait bound register of the -* DMA channel. This value contains the timer value used to trigger an -* interrupt when not enough packets have been received to reach the packet -* count threshold. -* -* The timer is in millisecond units with +/- 33% accuracy. -* -* ARGUMENTS: -* -* InstancePtr contains a pointer to the DMA channel to operate on. The DMA -* channel should be configured to use scatter gather in order for this function -* to be called. -* -* RETURN VALUE: -* -* The packet wait bound register contents for the DMA channel. -* -* NOTES: -* -* None. -* -******************************************************************************/ -u32 -XDmaChannel_GetPktWaitBound(XDmaChannel * InstancePtr) -{ - /* assert to verify input arguments */ - - XASSERT_NONVOID(InstancePtr != NULL); - XASSERT_NONVOID(InstancePtr->IsReady == XCOMPONENT_IS_READY); - - /* get the packet wait bound from the register and return it */ - - return XIo_In32(InstancePtr->RegBaseAddress + XDC_PWB_REG_OFFSET); -} |