xtemac.h

xilinx trimode mac driver for linux

/* $Id: */
/******************************************************************************
*
*       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
*       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
*       SOLUTIONS FOR XILINX DEVICES.  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 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.
*
*       (c) Copyright 2005-2006 Xilinx Inc.
*       All rights reserved.
* 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.
*
* 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., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*
******************************************************************************/
/*****************************************************************************/
/**
 *
 * @file xtemac.h
 *
 * The Xilinx Tri-Mode Ethernet driver component. This driver supports the
 * Virtex-4(TM) 10/100/1000 MAC (TEMAC).
 *
 * For a full description of TEMAC features, please see the HW spec. This driver
 * supports the following features:
 *   - Memory mapped access to host interface registers
 *   - API for polled frame transfers (FIFO direct HW configuration only)
 *   - API for interrupt driven frame transfers for HW configured with FIFO
 *     direct, or Scatter Gather DMA
 *   - Virtual memory support
 *   - Unicast, broadcast, and multicast receive address filtering
 *   - Full duplex operation (half duplex not supported)
 *   - Automatic source address insertion or overwrite (programmable)
 *   - Automatic PAD & FCS insertion and stripping (programmable)
 *   - Flow control
 *   - VLAN frame support
 *   - Pause frame support
 *   - Jumbo frame support
 *   - Data Realignment Engine (DRE)
 *   - Checksum offload
 *
 * <b>Driver Description</b>
 *
 * The device driver enables higher layer software (e.g., an application) to
 * communicate to the TEMAC. The driver handles transmission and reception of
 * Ethernet frames, as well as configuration and control. No pre or post
 * processing of frame data is performed. The driver does not validate the
 * contents of an incoming frame in addition to what has already occurred in HW.
 * A single device driver can support multiple devices even when those devices
 * have significantly different configurations.
 *
 * <b>Initialization & Configuration</b>
 *
 * The XTemac_Config structure is used by the driver to configure itself. This
 * configuration structure is typically created by the tool-chain based on HW
 * build properties.
 *
 * To support multiple runtime loading and initialization strategies employed
 * by various operating systems, the driver instance can be initialized in one
 * of the following ways:
 *
 *   - XTemac_Initialize(InstancePtr, DeviceId): The driver looks up its own
 *     configuration structure created by the tool-chain based on an ID provided
 *     by the tool-chain.
 *
 *   - XTemac_VmInitialize(InstancePtr, DeviceId, VirtualAddress): Operates
 *     like XTemac_Initialize() except the physical base address found in the
 *     configuration structure is replaced with the provided virtual address
 *
 *   - XTemac_CfgInitialize(InstancePtr, CfgPtr, VirtualAddress):  Uses a
 *     configuration structure provided by the caller. If running in a system
 *     with address translation, the provided virtual memory base address
 *     replaces the physical address present in the configuration structure.
 *
 * The device can be configured for 2 major modes of operation: FIFO direct,
 * or scatter gather DMA (SGDMA). Each of these modes are independent of one
 * another and have their own frame transfer API. This driver can manage an
 * arbitrary number of devices each with its own operating mode and supporting
 * features and options.
 *
 * The driver tries to use the features built into the device as described
 * by the configuration structure. So if the hardware is configured with
 * SGDMA, the driver expects to start the SGDMA channels and expects that
 * the user has set up the buffer descriptor lists.
 *
 * <b>Interrupts and Asynchronous Callbacks</b>
 *
 * The driver has no dependencies on the interrupt controller. It provides
 * one interrupt handler per mode of operation (FIFO, SGDMA) that can be
 * connected to the system interrupt controller by BSP/OS specific means.
 *
 * When an interrupt occurs, the handler will perform a small amount of
 * housekeeping work, determine the source of the interrupt, and call the
 * appropriate callback function. All callbacks are registered by the user
 * level application.
 *
 * SGDMA implements interrupt coalescing features that reduce the frequency
 * of interrupts. A more complete discussion of this feature occurs in the API
 * section below.
 *
 * <b>Device Reset</b>
 *
 * Some errors that can occur require a device reset. These errors are listed
 * in the XTemac_ErrorHandler() function typedef header. The user's error
 * callback handler is responsible for resetting and re-configuring the device.
 * When a device reset is required, XTemac_Reset() should be utilized.
 *
 * <b>Virtual Memory</b>
 *
 * This driver may be used in systems with virtual memory support by using one
 * of the initialization functions that supply the virtual memory address of
 * the device.
 *
 * All virtual to physical memory mappings must occur prior to accessing the
 * driver API. The driver does not support multiple virtual memory translations
 * that map to the same physical address.
 *
 * For DMA transactions, user buffers supplied to the driver must be in terms
 * of their physical address.
 *
 * <b>Transfer Mode APIs</b>
 *
 * Using the proper API depends on how the HW has been configured. There are
 * two interrupt driven modes (FIFO Direct, and SGDMA). FIFO Direct also
 * supports a polled mode of operation.
 *
 * It is the user's responsibilty to use the API that matches the device
 * configuration. Most API functions do not perform runtime checks to verify
 * proper configuration. If an API function is called in error on a device
 * instance, then that function may attempt to access registers that are not
 * present resulting in bus errors and/or corrupted data. Macros are defined
 * that help the user determine which API can be used.
 *
 * All API functions are prototyped in xtemac.h and are implemented in various
 * xtemac_*.c files by feature.
 *
 * The following sections discuss in more detail each of the available APIs.
 *
 * <b>FIFO Direct API</b>
 *
 * This device mode utilizes the processor to transfer data between user buffers
 * and the packet FIFOs. HW configured in this way uses the least amount of FPGA
 * resources but provides the lowest data throughput.
 *
 * This API allows user independent access to the data packet, packet length,
 * and event FIFOs. While more sophisticated device modes keep these FIFOs
 * in sync automatically, the user has the primary responsibility in FIFO
 * direct mode.
 *
 * The packet FIFOs contain the frame data while the length/status FIFOs contain
 * receive lengths, transmit lengths, and transmit statuses. When these FIFOs
 * go out of sync, then packet data will become corrupted.
 *
 * On the transmit side, the transmit packet FIFO may contain more than one
 * Ethernet packet placed there by XTemac_FifoWrite(). The number of packets it
 * may contain depends on its depth which is controlled at HW build time. For
 * each packet in the FIFO, the user must initiate a transmit by writing into
 * the transmit length FIFO (see XTemac_FifoSend()). The number of bytes
 * specified to transmit must match exactly the lengths of packets in the
 * packet FIFO. For example, if a 76 byte packet was written followed by a
 * 124 byte packet, then the transmit length FIFO must be written with 76
 * followed by 124. At the completion of the transmission, the transmit status
 * FIFO must be read to obtain the outcome of the operation. The first status
 * will be for the 76 byte packet followed by the 124 byte packet.
 *
 * If there is not enough data in the packet FIFO to complete a transmit
 * operation, an underrun condition will be reported. The frame that gets
 * transmitted in this case is forced to a corrupted state so that it
 * will flagged as invalid by other receivers.
 *
 * On the receive side, it is a little easier to keep things in sync because
 * the HW writes to the receive packet FIFO. Just like the transmit packet FIFO,
 * the receive packet FIFO can contain more than one received Ethernet frame.
 * Each time a length is extracted from the receive length FIFO (see
 * XTemac_FifoRecv()), then that many bytes must be read from the receive
 * packet FIFO by XTemac_FifoRead().
 *
 * The easiest way to keep these FIFOs in sync is to process a single frame at
 * a time. But when performance is an issue, it may be desirable to process
 * multiple or even partial frames from non-contiguous memory regions. The
 * examples that accompany this driver illustrate how these advanced frame
 * processing methods can be implemented.
 *
 * In interrupt driven mode, user callbacks are invoked by the interrupt handler
 * to signal that frames have arrived, frames have been transmitted, or an
 * error has occurred. When the XTE_POLLED_OPTION is set, the user must use
 * send and receive query status functions to determine when these events
 * occur.
 *
 * <b>SGDMA API</b>
 *
 * This API utilizes scatter-gather DMA (SGDMA) channels to transfer frame data
 * between user buffers and the packet FIFOs.
 *
 * The SGDMA engine uses buffer descriptors (BDs) to describe Ethernet frames.
 * These BDs are typically chained together into a list the HW follows when
 * transferring data in and out of the packet FIFOs. Each BD describes a memory
 * region containing either a full or partial Ethernet packet.
 *
 * The frequency of interrupts can be controlled with the interrupt coalescing
 * features of the SG DMA engine. These features can be used to optimize
 * interrupt latency and throughput for the user's network traffic conditions.
 * The packet threshold count will delay processor interrupts until a
 * programmable number of packets have arrived or have been transmitted. The
 * packet wait bound timer can be used to cause a processor interrupt even though
 * the packet threshold has not been reached. The timer begins counting after the
 * last packet is processed. If no other packet is processed as the timer
 * expires, then an interrupt will be generated.
 *
 * Another form of interrupt control is provided with the XTE_SGEND_INT_OPTION
 * option. When enabled, an interrupt will occur when SGDMA engine completes the
 * last BD to be processed and transitions to an idle state. This feature may be
 * useful when a set of BDs have been queued up and the user only wants to be
 * notified when they have all been processed by the HW. To use this feature
 * effectively, interrupt coalescing should be disabled (packet threshold = 0,
 * wait bound timer = 0), or the packet threshold should be set to a number
 * larger than the number of packets queued up.
 *
 * By default, the driver will set the packet threshold = 1, wait bound timer =
 * 0, and disable the XTE_SGEND_INT_OPTION. These settings will cause one
 * interrupt per packet.
 *
 * This API requires the user to understand the how the SGDMA driver operates.
 * The following paragraphs provide some explanation, but the user is encouraged
 * to read documentation in xdmav3.h and xdmabdv3.h as well as study example code
 * that accompanies this driver.
 *
 * The API is designed to get BDs to and from the SGDMA engine in the most
 * efficient means possible. The first step is to establish a  memory region to
 * contain all BDs for a specific channel. This is done with XTemac_SgSetSpace()
 * and assumes the memory region is non-cached. This function sets up a BD ring
 * that HW will follow as BDs are processed. The ring will consist of a user
 * defined number of BDs which will all be partially initialized. For example on
 * the transmit channel, the driver will initialize all BDs' so that they are
 * configured for transmit. The more fields that can be permanently setup at
 * initialization, then the fewer accesses will be needed to each BD while the
 * SGDMA engine is in operation resulting in better throughput and CPU
 * utilization. The best case initialization would require the user to set only
 * a frame buffer address and length prior to submitting the BD to the engine.
 *
 * BDs move through the engine with the help of functions XTemac_SgAlloc(),
 * XTemac_SgCommit(), XTemac_SgGetProcessed(), and XTemac_SgFree(). All these
 * functions handle BDs that are in place. That is, there are no copies of BDs
 * kept anywhere and any BD the user interacts with is an actual BD from the
 * same ring HW accesses. Changing fields within BDs is done through an API
 * defined in xdmabdv3.h as well as checksum offloading macros defined in
 * xtemac.h.
 *
 * BDs in the ring go through a series of states as follows:
 *   1. Idle. The driver controls BDs in this state.
 *   2. The user has data to transfer. XTemac_SgAlloc() is called to reserve
 *      BD(s). Once allocated, the user may setup the BD(s) with frame buffer
 *      address, length, and other attributes. The user controls BDs in this
 *      state.
 *   3. The user submits BDs to the SGDMA engine with XTemac_SgCommit. BDs in
 *      this state are either waiting to be processed by HW, are in process, or
 *      have been processed. The SGDMA engine controls BDs in this state.
 *   4. Processed BDs are retrieved with XTemac_SgGetProcessed() by the
 *      user. Once retrieved, the user can examine each BD for the outcome of
 *      the DMA transfer. The user controls BDs in this state. After examining
 *      the BDs the user calls XTemac_SgFree() which places the BDs back into
 *      state 1.
 *
 * Each of the four BD accessor functions operate on a set of BDs. A set is
 * defined as a segment of the BD ring consisting of one or more BDs.  The user
 * views the set as a pointer to the first BD along with the number of BDs for
 * that set. The set can be navigated by using macros XTemac_mSgRecvBdNext() or
 * XTemac_mSgSendBdNext(). The user must exercise extreme caution when changing
 * BDs in a set as there is nothing to prevent doing a mSgRecvBdNext past the
 * end of the set and modifying a BD out of bounds.
 *
 * XTemac_SgAlloc() + XTemac_SgCommit(), as well as XTemac_SgGetProcessed() +
 * XTemac_SgFree() are designed to be used in tandem. The same BD set retrieved
 * with SgAlloc should be the same one provided to HW with SgCommit. Same goes
 * with SgGetProcessed and SgFree.
 *
 * <b>SG DMA Troubleshooting</b>
 *
 * To verify internal structures of BDs and the BD ring, the function
 * XTemac_SgCheck() is provided. This function should be used as a debugging
 * or diagnostic tool. If it returns a failure, the user must perform more
 * in depth debugging to find the root cause.
 *
 * To avoid problems, do not use the following BD macros for transmit channel
 * BDs (XTE_SEND):
 *
 *   - XDmaBdV3_mClear()
 *   - XDmaBdV3_mSetRxDir()
 *
 * and for receive channel BDs (XTE_RECV):
 *
 *   - XDmaBdV3_mClear()
 *   - XDmaBdV3_mSetTxDir()
 *
 * <b>Alignment & Data Cache Restrictions</b>
 *
 * FIFO Direct:
 *
 *   - No frame buffer alignment restrictions for Tx or Rx
 *   - Buffers not aligned on a 4-byte boundary will take longer to process
 *     as the driver uses a small transfer buffer to realign them prior to
 *     packet FIFO access
 *   - Frame buffers may be in cached memory
 *
 * SGDMA Tx with DRE:
 *
 *   - No frame buffer alignment restrictions
 *   - If frame buffers exist in cached memory, then they must be flushed prior
 *     to committing them to HW
 *   - Descriptors must be 4-byte aligned
 *   - Descriptors must be in non-cached memory
 *
 * SGDMA Tx without DRE:
 *
 *   - Frame buffers must be 8-byte aligned
 *   - If frame buffers exist in cached memory, then they must be flushed prior
 *     to committing them to HW
 *   - Descriptors must be 4-byte aligned
 *   - Descriptors must be in non-cached memory
 *
 * SGDMA Rx with DRE:
 *
 *   - No frame buffer alignment restrictions
 *   - If frame buffers exist in cached memory, then the cache must be
 *     invalidated for the memory region containing the frame prior to data
 *     access
 *   - Descriptors must be 4-byte aligned
 *   - Descriptors must be in non-cached memory
 *
 * SGDMA Rx without DRE:
 *
 *   - Frame buffers must be 8-byte aligned
 *   - If frame buffers exist in cached memory, then the cache must be
 *     invalidated for the memory region containing the frame prior to data
 *     access
 *   - Descriptors must be 4-byte aligned
 *   - Descriptors must be in non-cached memory
 *
 * <b>Buffer Copying</b>
 *
 * The driver is designed for a zero-copy buffer scheme. That is, the driver will
 * not copy buffers. This avoids potential throughput bottlenecks within the
 * driver.
 *
 * The only exception to this is when buffers are passed to XTemac_FifoRead() and
 * XTemac_FifoWrite() on 1, 2, or 3 byte alignments. These buffers will be byte
 * copied into a small holding area on their way to or from the packet FIFOs.
 * For PLB TEMAC this holding area is 8 bytes each way. If byte copying is
 * required, then the transfer will take longer to complete.
 *
 * <b>Checksum Offloading</b>