mplclient.h

NATIONAL公司DP83816芯片Linux下驱动

//**********************************************************************
//
//  MPLCLIENT.H
//
//  Copyright (c) 2004 National Semiconductor Corporation.
//  All Rights Reserved
//
//  This is the main public include file for MPL client modules (Eg. NSM)
//  It is NOT meant to be used internally by MPL.
//
//  Note: This file includes all relavent MPL include files.
//  Therefore clients need only include this one file to obtain
//  all needed definitions to use the MPL interfaces.
// 
//**********************************************************************

#ifndef _MPLCLIENT_H_
#define _MPLCLIENT_H_

// Include platform customized data type definitions.
#include <oai.h>

// Include common data structures between MPL and clients
#include <mplcommon.h>

// Include Debug
#include <mpldebug.h>

// Include MPL diagnostics APIs
#ifdef MPL_DIAG_MODE
#endif //MPL_DIAG_MODE

// Include all task offload related definitions
#ifdef MPL_TASK_STAT
#include <mpltaskstat.h>
#endif //MPL_TASK_STAT

#ifdef MPL_TASK_VLAN
#include <mpltaskvlan.h>
#endif //MPL_TASK_VLAN

#ifdef MPL_TASK_CHKSUM
#include <mpltaskchksum.h>
#endif //MPL_TASK_CHKSUM

#ifdef MPL_TASK_RECEIVE_FILTER
#include <mpltaskrxfilter.h>
#endif // MPL_TASK_RECEIVE_FILTER

//************************* MPL CORE FUNCTION PROTOTYPES **********************
// MPL basic device operation (initialization, tx/rx, configuration) APIs 
//*****************************************************************************


// MPL Operational Mode
typedef enum {
      MPL_MODE_NORMAL, 
      MPL_MODE_MONITOR,
      MPL_MODE_LOAD_ONLY
} MPL_MODE;

// Transmit Capabilities
typedef struct _MPL_CAPS_TRANSMIT {
      NS_UINT8   priorityQCnt;
      NS_UINT16  fifoSize;
      NS_UINT16  maxDma;
      NS_UINT16  minDrain;
      NS_UINT16  minFill;
      NS_UINT16  maxPacketSize;
      NS_UINT    txFlags; // None Defined Yet
} MPL_CAPS_TRANSMIT;
 
// Receive Capabilities
typedef struct _MPL_CAPS_RECEIVE {
      NS_UINT8   priorityQCnt;
      NS_UINT16  fifoSize;
      NS_UINT16  maxDma;
      NS_UINT16  minDrain;
      NS_UINT16  maxPacketSize;
      NS_UINT    rxFlags; // None Defined Yet     
} MPL_CAPS_RECEIVE;

// Interrupt Capabilities
typedef struct _MPL_CAPS_INTERRUPT {
      NS_UINT16  maxTimerHold;
      NS_UINT16  maxTransmitHold;
      NS_UINT16  maxReceiveHold;
      NS_UINT    intrFlags; // None Defined Yet 
} MPL_CAPS_INTERRUPT;

// Link Capabilities
typedef struct _MPL_CAPS_LINK {
      NS_UINT           linkFlags;
#define  MPL_LINK_PAUSE_RECEIVE      0x00000001 // Can rx pause reqs, but not tx
#define  MPL_LINK_PAUSE_TRANSMIT     0x00000002 // Can tx pause reqs, but not rx

} MPL_CAPS_LINK;

// Wol Capabilities
typedef struct _MPL_CAPS_WOL {
      NS_UINT8   maxPatterns;
      NS_UINT16  maxPatternSize;
      NS_UINT    wolFlags; // None Defined Yet
} MPL_CAPS_WOL;

// Offload Task Capabilities
typedef struct _MPL_CAPS_TASK {

      // Statistics Task
      struct {
         NS_BOOLEAN  supported;
         NS_UINT     statFlags;      
#define MPL_TASK_STAT_ADV  0x00000001

      } stat;

      // Checksum Task
      struct {
         NS_BOOLEAN  supported;
         NS_UINT     chkSumFlags;      
#define MPL_TASK_CHKSUM_GLOBAL     0x00000001
#define MPL_TASK_CHKSUM_PERPACKET  0x00000002
#define MPL_TASK_CHKSUM_REJECT_IP  0x00000004
#define MPL_TASK_CHKSUM_REJECT_UDP 0x00000008
#define MPL_TASK_CHKSUM_REJECT_TCP 0x00000010

      } chkSum;

      // VLAN Task
      struct {
         NS_BOOLEAN  supported;
         NS_UINT16   maxFilterEntries;
         NS_UINT     vlanFlags;      
#define MPL_TASK_VLAN_DETECT_TAGS       0x00000001 //Rx Only - Reports Tag data
#define MPL_TASK_VLAN_REMOVE_TAGS       0x00000002
#define MPL_TASK_VLAN_DISCARD_TAGGED    0x00000004
#define MPL_TASK_VLAN_DISCARD_UNTAGGED  0x00000008
#define MPL_TASK_VLAN_PERPACKET         0x00000010 //Tx Only
#define MPL_TASK_VLAN_FILTER     0x00000020 // Only when maxFilterEntries > 0x0

      } vlan;

      // Receive Filter Task
      struct {
         NS_BOOLEAN  supported;
         NS_UINT16   maxFilterEntries;
         NS_UINT     rxFilterFlags;
#define MPL_TASK_FILTER_MCAST    0x00000001 // Support Multicast Listen List
#define MPL_TASK_FILTER_UCAST    0x00000002 // Support Unicast Listen List
#define MPL_TASK_FILTER_PERFECT  0x00000004 // Support Perfect Filtering

      } rxFilter;

} MPL_CAPS_TASK;

// Device Capabilities Structure
typedef struct _MPL_CAPS {
      MPL_CAPS_TRANSMIT   txCaps;
      MPL_CAPS_RECEIVE    rxCaps;
      MPL_CAPS_INTERRUPT  intrCaps;
      MPL_CAPS_LINK       linkCaps;
      MPL_CAPS_WOL        wolCaps;
      MPL_CAPS_TASK       taskCaps;
} MPL_CAPS;

// Transmit Engine Configuration Structure
typedef struct MPL_TRANSMIT_CFG {
      NS_UINT8  priorityQueueCnt;
#define MPL_TRANSMIT_MAX_PRIORITYQ_CNT 4
      NS_UINT  descCnt[MPL_TRANSMIT_MAX_PRIORITYQ_CNT];
      NS_UINT  fillThreshold;
      NS_UINT  drainThreshold;
      NS_UINT  maxDmaBurst;
      NS_UINT  maxIndications;

      NS_UINT  cfgFlags;
#define MPL_TRANSMIT_CFG_FIFO     0x00000001
#define MPL_TRANSMIT_CFG_QUEUES   0x00000002
#define MPL_TRANSMIT_CFG_AUTO_PAD 0x00000004
#define MPL_TRANSMIT_CFG_QUEUE_RR 0x00000008 // En round-robin algo btn queues

} MPL_TRANSMIT_CFG;

// Receive Engine Configuration Structure
typedef struct MPL_RECEIVE_CFG {
      NS_UINT8  priorityQueueCnt;
#define MPL_RECEIVE_MAX_PRIORITYQ_CNT 1
      NS_UINT  descCnt[MPL_RECEIVE_MAX_PRIORITYQ_CNT];
      NS_UINT  drainThreshold;
      NS_UINT  maxDmaBurst;
      NS_UINT  maxIndications;

      NS_UINT  cfgFlags;
#define MPL_RECEIVE_CFG_FIFO    0x00000001
#define MPL_RECEIVE_CFG_QUEUES  0x00000002
} MPL_RECEIVE_CFG;

// Link Negotiation Mode
typedef enum {
      MPL_LINK_MODE_AUTO,
      MPL_LINK_MODE_FORCED 
} MPL_LINK_NEGOTIATION;

// Link Speed
typedef enum {
      MPL_LINK_SPEED_HUNDREDMBPS,
      MPL_LINK_SPEED_TENMBPS 
} MPL_LINK_SPEED;

// Link Duplex Type
typedef enum {
      MPL_LINK_DUPLEX_FULL,
      MPL_LINK_DUPLEX_HALF
} MPL_LINK_DUPLEX;

// Link Configuration Structure
typedef struct _MPL_LINK_CFG {
      MPL_LINK_NEGOTIATION mode;
      MPL_LINK_SPEED       speed;
      MPL_LINK_DUPLEX      duplex;

#define  MPL_LINK_PAUSE_SYMMETRICAL  \
              (MPL_LINK_PAUSE_TRANSMIT | MPL_LINK_PAUSE_RECEIVE)
#define  MPL_LINK_PAUSE_NONE 0x0

      NS_UINT              pauseType;
      NS_UINT              pauseCtr;
      NS_UINT              pauseRxDALO;
      NS_UINT              pauseRxDAHI;
      NS_UINT              pauseRxSTLO;
      NS_UINT              pauseRxSTHI;
} MPL_LINK_CFG;

// Link Status Structure
typedef enum _MPL_LINK_STATUS {
      MPL_LINK_STATUS_NONE,
      MPL_LINK_STATUS_DOWN,
      MPL_LINK_STATUS_ACTIVE,
      MPL_LINK_STATUS_UP
} MPL_LINK_STATUS;

// Device Ids
typedef enum {
      MPL_DEVICE_ID_UNKNOWN,
      MPL_DEVICE_ID_DP83815,
      MPL_DEVICE_ID_DP83816,
      MPL_DEVICE_ID_DP83818
} MPL_DEVICE_ID;

// MPL Packet Fragment Descriptor
typedef struct _MPL_PKT_FRAG {
      struct _MPL_PKT_FRAG  *pNextFrag;
      NS_UINT                fragSize;
      NS_ADDR                physAddr;
      NS_UINT8              *pAddr;
      NS_VOID               *pPacketHndl;
      NS_VOID               *pMplPrivate;
      NS_VOID               *pNsmPrivate;
} MPL_PKT_FRAG;

// MPL Packet Tx Out-Of-Band data - MPL client should not modify this directly,
//  instead Call MplSetPacketXXX functions
typedef struct _MPL_PKT_TRANSMIT_OOB {
      NS_UINT32   cmdSts;
      NS_UINT32   extCtl; // Extended Control
      NS_UINT8    pQueue;
} MPL_PKT_TRANSMIT_OOB;


// MPL Packet Rx Out-Of-Band data - MPL client should not modify this directly,
//  instead Call MplQueryPacketXXX functions
typedef struct _MPL_PKT_RECEIVE_OOB {
      NS_UINT32   cmdSts;
      NS_UINT32   extSts; // Extended Status
} MPL_PKT_RECEIVE_OOB;


// MPL Packet Descriptor
typedef struct _MPL_PKT {
      struct _MPL_PKT *pNextPacket;
      NS_UINT          fragCount;
      MPL_PKT_FRAG    *pFragHead;

      union {
          MPL_PKT_TRANSMIT_OOB tx;
          MPL_PKT_RECEIVE_OOB  rx;
      } OOB;
#define txOOB OOB.tx
#define rxOOB OOB.rx

      MPL_STATUS       packetStatus;
      NS_UINT          packetSize;
      NS_VOID         *pMplPrivate;
      NS_VOID         *pNsmPrivate;
} MPL_PKT;

// Transmit Done Indication (MPL to NSM)
typedef struct _MPL_TRANSMIT_DONE {
      NS_VOID         *pNsmPrivate;
      MPL_STATUS       packetStatus;
      NS_UINT32        cmdSts;
} MPL_TRANSMIT_DONE;

// Power State
typedef enum _MPL_POWER_STATE {
      MPL_POWER_STATE_LOW,
      MPL_POWER_STATE_HIGH
} MPL_POWER_STATE;

// WoL Pattern Container
typedef struct _MPL_WOL_PATTERN {
      NS_UINT   patternSize;
      NS_UINT8 *pPattern;
      NS_UINT   maskSize;
      NS_UINT8 *pMask;
} MPL_WOL_PATTERN;


//+++++ Device Initialization and Shutdown APIs
//############################################

#if defined(__cplusplus)
extern "C"
{
#endif

//*****************************************************************************
//   MplInitialize 
//      Allocate and initialize a MPL context fot the device.
//
//   Parameters
//      pNsmHandle
//         NSM device handle for the device hardware.  This handle is retained 
//          by MPL and passed in to subsequent calls to the NSM.
//      pBaseAddr
//         The logical base address for the device.
//      diagEnable
//         A NS_TRUE notifies MPL to go into a diagnostic mode where MPL lets 
//          the diag application to control the adapter, MPL now handles only
//          Txd and RXD ring operation. For most production drivers this should
//          be passed as NS_FALSE.
//      pMplHandle
//         MPL handle for the device’s context.  The NSM must retain this handle
//          and pass it for all subsequent MPL calls.
//
//   Return Value
//      NS_STATUS_SUCCESS
//         The device was successfully initialized and the MPL context is 
//          returned
//      NS_STATUS_INVALID_PARAM
//         An invalid parameter value was detected
//      NS_STATUS_RESOURCES
//         Unable to initialize a context (lack of system resources)
//      NS_STATUS_HARDWARE_FAILURE
//         Unable to initialize a context (unexpected h/w error)
//         or failed to detect MacPhyter device
//
//*****************************************************************************
MPL_STATUS
   MplInitialize (
      IN NS_VOID       *pNsmHandle,
      IN NS_VOID       *pBaseAddr,
      IN NS_BOOLEAN     diagEnable,
      OUT NS_VOID     **pMplHandle
      );

//*****************************************************************************
//   MplOpen
//      Opens the device for network operation. 
//
//   Parameters
//      pMplHandle
//         MPL device handle returned following a call to MplInitialize. 
//
//   Return Value
//      NS_STATUS_SUCCESS
//         The device was successfully opened and is ready for network operation
//      NS_STATUS_INVALID_PARM
//         An invalid parameter value was detected or this function is called 
//          prior to MplInitialize
//      NS_STATUS_HARDWARE_FAILURE
//         Unexpected hardware error
//
//*****************************************************************************
MPL_STATUS
   MplOpen (
      IN NS_VOID       *pMplHandle
      );


//*****************************************************************************
//   MplClose
//      Closes the network device, disabling network transmission/reception and
//       interrupts. 
//
//   Parameters
//      pMplHandle
//         MPL device handle returned following a call to MplInitialize
//
//   Return Value
//      NS_STATUS_SUCCESS
//         The device was successfully closed
//      NS_STATUS_INVALID_PARM
//         An invalid parameter value was detected or this function is called 
//          prior to MplInitialize or MplOpen
//
//*****************************************************************************
MPL_STATUS
   MplClose (
      IN NS_VOID       *pMplHandle
      );

//*****************************************************************************
//   MplUnload
//      Shuts down the device hardware and frees all allocated resources claimed
//       by MplInitialize. 
//
//   Parameters
//      pMplHandle
//         MPL device handle returned following a call to MplInitialize
//
//   Return Value
//      NS_STATUS_SUCCESS
//         MPL was successfully unloaded and all resources released.
//      NS_STATUS_INVALID_PARM
//         An invalid parameter value was detected or this function is called 
//          prior to MplInitialize
//
//*****************************************************************************
MPL_STATUS
   MplUnload (
      IN NS_VOID       *pMplHandle
      );

//*****************************************************************************
//   MplMacReset
//      Resets the network device. 
//
//   Parameters
//      pMplHandle
//         MPL device handle returned following a call to MplInitialize
//
//   Return Value
//      NS_STATUS_SUCCESS
//         The network device was successfully reset.
//      NS_STATUS_HARDWARE_FAILURE
//         Unexpected hardware error
//
//*****************************************************************************
MPL_STATUS
   MplMacReset (
      IN NS_VOID       *pMplHandle
      );


//*****************************************************************************
//   MplGetCaps
//      Returns the capabilities of the device and the MPL implementation. 
//
//   Parameters
//      pMplHandle
//         MPL device handle returned following a call to MplInitialize
//      pMplCaps
//         Pointer to a caller allocated MPL_CAPS structure in which the 
//          capabilities of the device and MPL is returned
//