xtemac.h

xilinx trimode mac driver for linux

 *
 * If configured, the device can compute a 16-bit checksum from frame data. In
 * most circumstances this can lead to a substantial gain in throughput.
 *
 * For Tx, the SW can specify where in the frame the checksum calculation is
 * to start, where it should be inserted, and a seed value. The checksum is
 * calculated from the start point through the end of frame. For Rx, the 15th
 * byte to end of frame is checksummed. This is the entire Ethernet payload
 * for non-VLAN frames.
 *
 * Setting up and accessing checksum data is done with XTemac API macro calls
 * on buffer descriptors on a per-frame basis.
 *
 * Since this HW implementation is general purpose in nature system SW must
 * perform pre and post frame processing to obtain the desired results for the
 * types of packets being transferred. Most of the time this will be TCP/IP
 * traffic.
 *
 * TCP/IP and UDP/IP frames contain separate checksums for the IP header and
 * UDP/TCP header+data. With this HW implementation, the IP header checksum
 * cannot be offloaded. Many stacks that support offloading will compute the IP
 * header if required and use HW to compute the UDP/TCP header+data checksum.
 * There are other complications concerning the IP pseudo header that must be
 * taken into consideration. Readers should consult a TCP/IP design reference
 * for more details.
 *
 * There are certain device options that will affect the checksum calculation
 * performed by HW for Tx:
 *
 *   - FCS insertion disabled (XTE_FCS_INSERT_OPTION): SW is required to
 *     calculate and insert the FCS value at the end of the frame, but the
 *     checksum must be known ahead of time prior to calculating the FCS.
 *     Therefore checksum offloading cannot be used in this situation.
 *
 * And for Rx:
 *
 *   - FCS/PAD stripping disabled (XTE_FCS_STRIP_OPTION): The 4 byte FCS at the
 *     end of frame will be included in the HW calculated checksum. SW must
 *     subtract out this data.
 *
 *   - FCS/PAD stripping disabled (XTE_FCS_STRIP_OPTION): For frames smaller
 *     than 64 bytes, padding will be included in the HW calculated checksum.
 *     SW must subtract out this data. It may be better to allow the TCP/IP
 *     stack verify checksums for this type of packet.
 *
 *   - VLAN enabled (XTE_VLAN_OPTION): The 4 extra bytes in the Ethernet header
 *     affect the HW calculated checksum. SW must subtract out the 1st two
 *     16-bit words starting at the 15th byte.
 *
 * <b>PHY Communication</b>
 *
 * Prior to PHY access, the MDIO clock must be setup. This driver will set a
 * safe default that should work with PLB bus speeds of up to 150 MHz and keep
 * the MDIO clock below 2.5 MHz. If the user wishes faster access to the PHY
 * then the clock divisor can be set to a different value (see
 * XTemac_PhySetMdioDivisor()).
 *
 * MII register access is performed through the functions XTemac_PhyRead() and
 * XTemac_PhyWrite().
 *
 * <b>Link Sync</b>
 *
 * When the device is used in a multispeed environment, the link speed must be
 * explicitly set using XTemac_SetOperatingSpeed() and must match the speed the
 * PHY has negotiated. If the speeds are mismatched, then the MAC will not pass
 * traffic.
 *
 * Using the XTE_ANEG_OPTION and the provided callback handler, SW can be
 * notified when the PHY has completed auto-negotiation.
 *
 * <b>Asserts</b>
 *
 * Asserts are used within all Xilinx drivers to enforce constraints on argument
 * values. Asserts can be turned off on a system-wide basis by defining, at
 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
 * is recommended that users leave asserts on during development. For deployment
 * use -DNDEBUG compiler switch to remove assert code.
 *
 * <b>Driver Errata</b>
 *
 *   - A dropped receive frame indication may be reported by the driver after
 *     calling XTemac_Stop() followed by XTemac_Start(). This can occur if a
 *     frame is arriving when stop is called.
 *   - On Rx with checksum offloading enabled and FCS/PAD stripping disabled,
 *     FCS and PAD data will be included in the checksum result.
 *   - On Tx with checksum offloading enabled and auto FCS insertion disabled,
 *     the user calculated FCS will be included in the checksum result.
 *
 * @note
 *
 * Xilinx drivers are typically composed of two components, one is the driver
 * and the other is the adapter.  The driver is independent of OS and processor
 * and is intended to be highly portable.  The adapter is OS-specific and
 * facilitates communication between the driver and an OS.
 * <br><br>
 * This driver is intended to be RTOS and processor independent. Any needs for
 * dynamic memory management, threads or thread mutual exclusion, or cache
 * control must be satisfied by the layer above this driver.
 *
 * <pre>
 * MODIFICATION HISTORY:
 *
 * Ver   Who  Date     Changes
 * ----- ---- -------- -------------------------------------------------------
 * 1.00a rmm  06/01/05 First release
 * 1.00b rmm  09/23/05 Replaced XTemac_GetPhysicalInterface() with macro
 *                     XTemac_mGetPhysicalInterface(). Implemented
 *                     XTemac_PhyRead/Write() functions. Redesigned MII/RGMII/
 *                     SGMII status functions. Renamed most of the host
 *                     registers to reflect latest changes in HW spec, added
 *                     XST_FIFO_ERROR return code to polled FIFO query
 *                     functions.
 * 2.00a rmm  11/21/05 Switched to local link DMA driver, removed simple-DMA
 *                     mode, added auto-negotiation callback, added checksum
 *                     offload access macros, removed XST_SEND_ERROR error
 *                     class completely since TSR bits went away, removed
 *                     XST_FAILURE return code for XTemac_FifoQuerySendStatus(),
 *                     added static init feature, changed XTE_FCS_STRIP_OPTION
 *                     to default to set.
 * </pre>
 *
 *****************************************************************************/

#ifndef XTEMAC_H /* prevent circular inclusions */
#define XTEMAC_H /* by using protection macros */

#ifdef __cplusplus
extern "C" {
#endif

/***************************** Include Files *********************************/

#include <asm/delay.h>
#include "xbasic_types.h"
#include "xstatus.h"
#include "xparameters.h"
#include "xipif_v1_23_b.h"
#include "xpacket_fifo_v2_00_a.h"
#include "xdmav3.h"
#include "xtemac_l.h"

/************************** Constant Definitions *****************************/

/*
 * Device information
 */
#define XTE_DEVICE_NAME     "xtemac"
#define XTE_DEVICE_DESC     "Xilinx Tri-speed 10/100/1000 MAC"


/** @name Configuration options
 *
 * Device configuration options. See the XTemac_SetOptions(),
 * XTemac_ClearOptions() and XTemac_GetOptions() for information on how to use
 * options.
 *
 * The default state of the options are noted and are what the device and driver
 * will be set to after calling XTemac_Reset() or XTemac_Initialize().
 *
 * @{
 */

#define XTE_PROMISC_OPTION               0x00000001
/**< Accept all incoming packets.
 *   This option defaults to disabled (cleared) */

#define XTE_JUMBO_OPTION                 0x00000002
/**< Jumbo frame support for Tx & Rx.
 *   This option defaults to disabled (cleared) */

#define XTE_VLAN_OPTION                  0x00000004
/**< VLAN Rx & Tx frame support.
 *   This option defaults to disabled (cleared) */

#define XTE_FLOW_CONTROL_OPTION          0x00000010
/**< Enable recognition of flow control frames on Rx
 *   This option defaults to enabled (set) */

#define XTE_FCS_STRIP_OPTION             0x00000020
/**< Strip FCS and PAD from incoming frames. Note: PAD from VLAN frames is not
 *   stripped.
 *   This option defaults to disabled (set) */

#define XTE_FCS_INSERT_OPTION            0x00000040
/**< Generate FCS field and add PAD automatically for outgoing frames.
 *   This option defaults to enabled (set) */

#define XTE_LENTYPE_ERR_OPTION           0x00000080
/**< Enable Length/Type error checking for incoming frames. When this option is
 *   set, the MAC will filter frames that have a mismatched type/length field
 *   and if XTE_REPORT_RXERR_OPTION is set, the user is notified when these
 *   types of frames are encountered. When this option is cleared, the MAC will
 *   allow these types of frames to be received.
 *
 *   This option defaults to enabled (set) */

#define XTE_SGEND_INT_OPTION             0x00000100
/**< Enable the SGEND interrupt with SG DMA. When enabled, an interrupt will
 *   be triggered when the end of the buffer descriptor list is reached. The
 *   interrupt will occur despite interrupt coalescing settings.
 *   This option defaults to disabled (cleared) */

#define XTE_POLLED_OPTION                0x00000200
/**< Polled mode communications. Enables use of XTemac_FifoQuerySendStatus()
 *   and XTemac_FifoQueryRecvStatus(). Users may enter/exit polled mode
 *   from any interrupt driven mode.
 *   This option defaults to disabled (cleared) */

#define XTE_REPORT_RXERR_OPTION          0x00000400
/**< Enable reporting of dropped receive packets due to errors
 *   This option defaults to enabled (set) */

#define XTE_TRANSMITTER_ENABLE_OPTION    0x00000800
/**< Enable the transmitter.
 *   This option defaults to enabled (set) */

#define XTE_RECEIVER_ENABLE_OPTION       0x00001000
/**< Enable the receiver
 *   This option defaults to enabled (set) */

#define XTE_BROADCAST_OPTION             0x00002000
/**< Allow reception of the broadcast address
 *   This option defaults to enabled (set) */

#define XTE_MULTICAST_CAM_OPTION         0x00004000
/**< Allows reception of multicast addresses programmed into CAM
 *   This option defaults to disabled (clear) */

#define XTE_REPORT_TXSTATUS_OVERRUN_OPTION 0x00008000
/**< Enable reporting the overrun of the Transmit status FIFO. This type of
 *   error is latched by HW and can be cleared only by a reset. SGDMA systems,
 *   this option should be enabled since the DMA engine is responsible for
 *   keeping this from occurring. For FIFO direct systems, this error may be
 *   a nuisance because a SW system may be able to transmit frames faster
 *   than the interrupt handler can handle retrieving statuses.
 *   This option defaults to enabled (set) */

#define XTE_ANEG_OPTION                  0x00010000
/**< Enable autonegotiation interrupt
     This option defaults to disabled (clear) */

#define XTE_DEFAULT_OPTIONS                     \
    (XTE_FLOW_CONTROL_OPTION |                  \
     XTE_BROADCAST_OPTION |                     \
     XTE_FCS_INSERT_OPTION |                    \
     XTE_FCS_STRIP_OPTION |                     \
     XTE_LENTYPE_ERR_OPTION |                   \
     XTE_TRANSMITTER_ENABLE_OPTION |            \
     XTE_REPORT_RXERR_OPTION |                  \
     XTE_REPORT_TXSTATUS_OVERRUN_OPTION |       \
     XTE_RECEIVER_ENABLE_OPTION)
/**< Default options set when device is initialized or reset */

/*@}*/

/** @name Direction identifiers
 *
 *  These are used by several functions and callbacks that need
 *  to specify whether an operation specifies a send or receive channel.
 * @{
 */
#define XTE_SEND    1
#define XTE_RECV    2
/*@}*/

/** @name Reset parameters
 *
 *  These are used by function XTemac_Reset().
 * @{
 */
#define XTE_RESET_HARD    1
#define XTE_NORESET_HARD  0
/*@}*/

/** @name XTemac_FifoWrite/Read() function arguments
 *
 *  These are used by XTemac_FifoWrite/Read() End Of Packet (Eop)
 *  parameter.
 * @{
 */
#define XTE_END_OF_PACKET   1   /**< The data written is the last for the
                                  *  current packet */
#define XTE_PARTIAL_PACKET  0   /**< There is more data to come for the
                                  *  current packet */
/*@}*/

/** @name Callback identifiers
 *
 * These constants are used as parameters to XTemac_SetHandler()
 * @{
 */
#define XTE_HANDLER_FIFOSEND     1
#define XTE_HANDLER_FIFORECV     2
#define XTE_HANDLER_SGSEND       5
#define XTE_HANDLER_SGRECV       6
#define XTE_HANDLER_ERROR        7
#define XTE_HANDLER_ANEG         8
/*@}*/


/* Constants to determine the configuration of the hardware device. They are
 * used to allow the driver to verify it can operate with the hardware.
 */
#define XTE_CFG_NO_DMA              1       /* No DMA */
#define XTE_CFG_SIMPLE_DMA          2       /* Simple DMA (not supported) */
#define XTE_CFG_DMA_SG              3       /* DMA scatter gather */

#define XTE_MULTI_CAM_ENTRIES       4       /* Number of storable addresses in
                                               the CAM */

#define XTE_MDIO_DIV_DFT            29      /* Default MDIO clock divisor */

/* Some default values for interrupt coalescing within the scatter-gather
 * DMA engine.
 */
#define XTE_SGDMA_DFT_THRESHOLD     1       /* Default pkt threshold */
#define XTE_SGDMA_MAX_THRESHOLD     1023    /* Maximum pkt theshold */
#define XTE_SGDMA_DFT_WAITBOUND     0       /* Default pkt wait bound (msec) */
#define XTE_SGDMA_MAX_WAITBOUND     1023    /* Maximum pkt wait bound (msec) */

/* The next few constants help upper layers determine the size of memory
 * pools used for Ethernet buffers and descriptor lists.
 */
#define XTE_MAC_ADDR_SIZE   6       /* six-byte MAC address */
#define XTE_MTU             1500    /* max MTU size of Ethernet frame */
#define XTE_JUMBO_MTU       8982    /* max MTU size of jumbo Ethernet frame */
#define XTE_HDR_SIZE        14      /* size of Ethernet header */
#define XTE_HDR_VLAN_SIZE   18      /* size of Ethernet header with VLAN */
#define XTE_TRL_SIZE        4       /* size of Ethernet trailer (FCS) */
#define XTE_MAX_FRAME_SIZE       (XTE_MTU + XTE_HDR_SIZE + XTE_TRL_SIZE)
#define XTE_MAX_VLAN_FRAME_SIZE  (XTE_MTU + XTE_HDR_VLAN_SIZE + XTE_TRL_SIZE)
#define XTE_MAX_JUMBO_FRAME_SIZE (XTE_JUMBO_MTU + XTE_HDR_SIZE + XTE_TRL_SIZE)

/* Constant values returned by XTemac_mGetPhysicalInterface(). Note that these
 * values match design parameters from the PLB_TEMAC spec
 */
#define XTE_PHY_TYPE_MII         0
#define XTE_PHY_TYPE_GMII        1
#define XTE_PHY_TYPE_RGMII_1_3   2
#define XTE_PHY_TYPE_RGMII_2_0   3
#define XTE_PHY_TYPE_SGMII       4
#define XTE_PHY_TYPE_1000BASE_X  5

/**************************** Type Definitions *******************************/


/** @name Typedefs for callback functions
 *
 * These callbacks are invoked in interrupt context.
 * @{
 */

/**
 * Callback invoked when frame(s) have been sent in interrupt driven FIFO
 * direct mode. To set this callback, invoke XTemac_SetHander() with
 * XTE_HANDLER_FIFOSEND in the HandlerType parameter.
 *
 * @param CallBackRef is user data assigned when the callback was set.
 * @param StatusCnt is the number of statuses read from the device indicating
 *        a successful frame transmit.
 *
 */
typedef void (*XTemac_FifoSendHandler)(void *CallBackRef, unsigned StatusCnt);

/**