/*
 *  Copyright 2003 by Texas Instruments Incorporated.
 *  All rights reserved. Property of Texas Instruments Incorporated.
 *  Restricted rights to use, duplicate or disclose this code are
 *  granted through contract.
 *  
 */
/* "@(#) DSP/BIOS 4.90.200 05-05-03 (barracuda-m04)" */
/*-----------------------------------------------------------------------*\
* EMI - Ethernet MAC Interface
*
* EMI.H
*
* This file contains the specification of the EMI device.
*
* NOTE:
*   When used in an multitasking environment, no EMI function may be
*   called while another EMI function is operating on the same EMI
*   handle in another thread. It is the responsibility of the application
*   to assure adherence to this restriction. This includes the ISR
*   function, which means interrupts should be disable while calling EMI
*   by masking the CPU interrupt onto which the EMAC is mapped.
*
\*-----------------------------------------------------------------------*/
#ifndef _CSL_EMI_H_
#define _CSL_EMI_H_

#if (EMAC_SUPPORT)
/*-----------------------------------------------------------------------*\
* NEW TYPES
\*-----------------------------------------------------------------------*/
#ifndef _CSL_EMI_TYPES
#define _CSL_EMI_TYPES
typedef unsigned int uint;
typedef void * Handle;
#endif

/*-----------------------------------------------------------------------*\
* STANDARD DATA STRUCTURES
\*-----------------------------------------------------------------------*/

/*-----------------------------------------------------------------------*\
* EMI_Pkt
*
* The packet structure defines the basic unit of memory used to hold data
* packets for the EMI device.
*
* A packet is comprised of one or more packet buffers. Each packet buffer
* contains a packet buffer header, and a pointer to the buffer data.
* The EMI_Pkt structure defines the packet buffer header.
*
* The pDataBuffer field points to the packet data. This is set when the
* buffer is allocated, and is not altered.
*
* BufferLen holds the the total length of the data buffer that is used to
* store the packet (or packet fragment). This size is set by the entity
* that originally allocates the buffer, and is not altered.
*
* The Flags field contains additional information about the packet
*
* ValidLen holds the length of the valid data currently contained in the
* data buffer.
*
* DataOffset is the byte offset from the start of the data buffer to the
* first byte of valid data. Thus (ValidLen+DataOffet)<=BufferLen.
*
* Note that for receive buffer packets, the DataOffset field may be
* assigned before there is any valid data in the packet buffer. This allows
* the application to reserve space at the top of data buffer for private
* use. In all instances, the DataOffset field must be valid for all packets
* handled by EMI.
*
* The data portion of the packet buffer represents a packet or a fragment
* of a larger packet. This is determined by the Flags parameter. At the
* start of every packet, the SOP bit is set in Flags. If the EOP bit is
* also set, then the packet is not fragmented. Otherwise; the next packet
* structure pointed to by the pNext field will contain the next fragment in
* the packet. On either type of buffer, when the SOP bit is set in Flags,
* then the PktChannel, PktLength, and PktFrags fields must also be valid.
* These fields contain additional information about the packet.
*
* The PktChannel field detetmines what channel the packet has arrived on,
* or what channel it should be transmitted on. The EMI library supports
* only a single receive channel, but allows for up to eight transmit
* channels. Transmit channels can be treated as round-robin or priority
* queues.
*
* The PktLength field holds the size of the entire packet. On single frag
* packets (both SOP and EOP set in BufFlags), PktLength and ValidLen will
* be equal.
*
* The PktFrags field holds the number of fragments (EMI_Pkt records) used
* to describe the packet. If more than 1 frag is present, the first record
* must have EMI_PKT_FLAGS_SOP flag set, with corresponding fields validated.
* Each frag/record must be linked list using the pNext field, and the final
* frag/record must have EMI_PKT_FLAGS_EOP flag set and pNext=0.
*
* In systems where the packet resides in cacheable memory, the data buffer
* must start on a cache line boundary and be an even multiple of cache
* lines in size. The EMI_Pkt header must not appear in the same cache line
* as the data portion of the packet. On multi-fragment packets, some packet
* fragments may reside in cacheable memory where others do not.
*
* ** NOTE: It is up to the caller to assure that all packet buffers    **
* ** residing in cacheable memory are not currently stored in L1 or L2 **
* ** cache when passed to any EMI function                             **
*
* Some of the packet Flags can only be set if the device is in the
* proper configuration to receive the corresponding frames. In order to
* enable these flags, the following modes must be set:
*       RxCrc Flag  : RXCRC Mode in EMI_Config
*       RxErr Flags : PASSERROR Mode in EMI_Config
*       RxCtl Flags : PASSCONTROL Mode in EMI_Config
*       RxPrm Flag  : EMI_RXFILTER_ALL in EMI_setReceiveFilter()
*
\*-----------------------------------------------------------------------*/
typedef struct _EMI_Pkt {
    struct _EMI_Pkt *pPrev;       /* Previous record                       */
    struct _EMI_Pkt *pNext;       /* Next record                           */
    Uint8           *pDataBuffer; /* Pointer to Data Buffer                */
    Uint32          BufferLen;    /* Physical Length of buffer (read only) */
    Uint32          Flags;        /* Packet Flags                          */
    Uint32          ValidLen;     /* Length of valid data in buffer        */
    Uint32          DataOffset;   /* Byte offset to valid data             */
    Uint32          PktChannel;   /* Tx/Rx Channel/Priority 0-7 (SOP only) */
    Uint32          PktLength;    /* Length of Packet (SOP only)           */
                                  /* (same as ValidLen on single frag Pkt) */
    Uint32          PktFrags;     /* Number of frags in packet (SOP only)  */
                                  /* (frag is EMI_Pkt record - normally 1) */
    } EMI_Pkt;

/*
// Packet Buffer Flags set in Flags
*/
#define EMI_PKT_FLAGS_SOP         0x80000000u /* Start of packet           */
#define EMI_PKT_FLAGS_EOP         0x40000000u /* End of packet             */

/*
// The Following Packet flags are set in Flags on RX packets only
*/
#define EMI_PKT_FLAGS_HASCRC      0x04000000u /* RxCrc: PKT has 4byte CRC  */
#define EMI_PKT_FLAGS_JABBER      0x02000000u /* RxErr: Jabber             */
#define EMI_PKT_FLAGS_OVERSIZE    0x01000000u /* RxErr: Oversize           */
#define EMI_PKT_FLAGS_FRAGMENT    0x00800000u /* RxErr: Fragment           */
#define EMI_PKT_FLAGS_UNDERSIZED  0x00400000u /* RxErr: Undersized         */
#define EMI_PKT_FLAGS_CONTROL     0x00200000u /* RxCtl: Control Frame      */
#define EMI_PKT_FLAGS_OVERRUN     0x00100000u /* RxErr: Overrun            */
#define EMI_PKT_FLAGS_CODEERROR   0x00080000u /* RxErr: Code Error         */
#define EMI_PKT_FLAGS_ALIGNERROR  0x00040000u /* RxErr: Alignment Error    */
#define EMI_PKT_FLAGS_CRCERROR    0x00020000u /* RxErr: Bad CRC            */
#define EMI_PKT_FLAGS_NOMATCH     0x00010000u /* RxPrm: No Match           */


/*-----------------------------------------------------------------------*\
* EMI_Config
*
* The config structure defines how the EMI device should operate. It is
* passed to the device when the device is opened, and remains in effect
* until the device is closed.
*
* The following is a short description of the configuration fields:
*
* ModeFlags    - Specify the Fixed Operating Mode of the Device
* EMI_CONFIG_MODEFLG_CHPRIORITY  - Treat TX channels as Priority Levels
*                                  (Channel 7 is highest, 0 is lowest)
* EMI_CONFIG_MODEFLG_MACLOOPBACK - Set MAC in Internal Loopback for Testing
* EMI_CONFIG_MODEFLG_RXCRC       - Include the 4 byte EtherCRC in RX frames
* EMI_CONFIG_MODEFLG_TXCRC       - Assume TX Frames Include 4 byte EtherCRC
* EMI_CONFIG_MODEFLG_PASSERROR   - Receive Error Frames for Testing
* EMI_CONFIG_MODEFLG_PASSCONTROL - Receive Control Frames for Testing
*
* MdioModeFlags - Specify the MDIO/PHY Operation (See EMIMDIO.H)
*
* TxChannels    - Number of TX Channels to use (1-8, usually 1)
*
* MacAddr       - Device MAC address
*
* RxMaxPktPool  - Max Rx packet buffers to get from pool
*                 (Must be in the range of 8 to 192)
*
* A list of callback functions is used to register callback functions with
* a particular instance of the EMI peripheral. Callback functions are
* used by EMI to communicate with the application. These functions are
* REQUIRED for operation. The same callback table can be used for multiple
* driver instances.
*
* The callback functions can be used by EMI during any EMI function, but
* mostly occur during calls to EMI_statusIsr() and EMI_statusPoll().
*
* pfcbGetPacket -  Called by EMI to get a free packet buffer from the
*                  application layer for receive data. This function
*                  should return NULL is no free packets are available.
*                  The size of the packet buffer must be large enough
*                  to accommodate a full sized packet (1514 or 1518
*                  depending on the EMI_CONFIG_MODEFLG_RXCRC flag), plus
*                  any application buffer padding (DataOffset).
*
* pfcbFreePacket - Called by EMI to give a free packet buffer back to
*                  the application layer. This function is used to
*                  return transmit packets. Note that at the time of the
*                  call, structure fields other than pDataBuffer and
*                  BufferLen are in an undefined state.
*
* pfcbRxPacket   - Called to give a received data packet to the application
*                  layer. The applicaiton must accept the packet.
*                  When the application is finished with the packet, it
*                  can return it to its own free queue.
*
*                  This function also returns a pointer to a free packet to
*                  replace the received packet on the EMAC free list. It
*                  returns NULL when no free packets are available. The
*                  return packet is the same as would be returned by
*                  pfcbGetPacket.
*
*                  Thus if a newly received packet is not desired, it can
*                  simply be returned to EMI via the return value.
*
* pfcbStatus     - Called to indicate to the application that it
*                  should call EMI_getStatus() to read the current
*                  device status. This call is made when device status
*                  changes.
*
* pfcbStatistics - Called to indicate to the application that it
*                  should call EMI_getStatistics() to read the
*                  current Ethernet statistics. Called when the
*                  statistic counters are to the point of overflow.
*
* The hApplication calling calling argument is the application's handle
* as supplied to the EMI device in the EMI_open() function.
\*-----------------------------------------------------------------------*/
typedef struct _EMI_Config {
    uint        ModeFlags;      /* Configuation Mode Flags                */
    uint        MdioModeFlags;  /* EMIMDIO Mode Flags (see EMIMDIO.H)     */
    uint        TxChannels;     /* Number of Tx Channels to use (1-8)     */
    Uint8       MacAddr[6];     /* Mac Address                            */
    uint        RxMaxPktPool;   /* Max Rx packet buffers to get from pool */
    EMI_Pkt *   (*pfcbGetPacket)(Handle hApplication);
    void        (*pfcbFreePacket)(Handle hApplication, EMI_Pkt *pEmiPacket);
    EMI_Pkt *   (*pfcbRxPacket)(Handle hApplication, EMI_Pkt *pEmiPacket);
    void        (*pfcbStatus)(Handle hApplication);
    void        (*pfcbStatistics)(Handle hApplication);
} EMI_Config;

/*
//  Configuration Mode Flags
*/
#define EMI_CONFIG_MODEFLG_CHPRIORITY  0x0001 /* Use Tx channel priority  */
#define EMI_CONFIG_MODEFLG_MACLOOPBACK 0x0002 /* MAC internal loopback    */
#define EMI_CONFIG_MODEFLG_RXCRC       0x0004 /* Include CRC in RX frames */
#define EMI_CONFIG_MODEFLG_TXCRC       0x0008 /* Tx frames include CRC    */
#define EMI_CONFIG_MODEFLG_PASSERROR   0x0010 /* Pass error frames            */
#define EMI_CONFIG_MODEFLG_PASSCONTROL 0x0020 /* Pass control frames          */

/*-----------------------------------------------------------------------*\
* EMI_Status
*
* The status structure contains information about the MAC's run-time
* status.
*
* The following is a short description of the configuration fields:
*
* MdioLinkStatus - Current link status (non-zero on good link) (see EMIMDIO.H)
*
* PhyDev         - Current PHY device in use (0-31)
*
* RxPktHeld      - Current number of Rx packets held by the EMI device
*
* TxPktHeld      - Current number of Tx packets held by the EMI device
*
* FatalError     - Fatal Error Code (TBD)
\*-----------------------------------------------------------------------*/
typedef struct _EMI_Status {
    uint        MdioLinkStatus; /* EMIMDIO Link status (see EMIMDIO.H)   */
    uint        PhyDev;         /* Current PHY device in use (0-31)      */
    uint        RxPktHeld;      /* Number of packets held for Rx         */
    uint        TxPktHeld;      /* Number of packets held for Tx         */
    uint        FatalError;     /* Fatal Error when non-zero             */
} EMI_Status;


/*-----------------------------------------------------------------------*\
* EMI_Statistics
*
* The statistics structure is the used to retrieve the current count
* of various packet events in the system. These values represent the
* delta values from the last time the statistics were read.
\*-----------------------------------------------------------------------*/
typedef struct _EMI_Statistics {
    Uint32 RxGoodFrames;     /* Good Frames Received                         */
    Uint32 RxBCastFrames;    /* Good Broadcast Frames Received               */
    Uint32 RxMCastFrames;    /* Good Multicast Frames Received               */
    Uint32 RxPauseFrames;    /* PauseRx Frames Received                      */
    Uint32 RxCRCErrors;      /* Frames Received with CRC Errors              */
    Uint32 RxAlignCodeErrors;/* Frames Received with Alignment/Code Errors   */
    Uint32 RxOversized;      /* Oversized Frames Received                    */
    Uint32 RxJabber;         /* Jabber Frames Received                       */
    Uint32 RxUndersized;     /* Undersized Frames Received                   */
    Uint32 RxFragments;      /* Rx Frame Fragments Received                  */
    Uint32 RxFiltered;       /* Rx Frames Filtered Based on Address          */
    Uint32 RxQOSFiltered;    /* Rx Frames Filtered Based on QoS Filtering    */