/******************************************************************************* Ethernet Library Interface Definition Summary: This file contains the Application Program Interface (API) definition for the Ethernet peripheral library. Description: This library provides a low-level abstraction of the Ethernet module on Microchip PIC32MX family microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. *******************************************************************************/ //DOM-IGNORE-BEGIN /******************************************************************************* FileName: eth.h Processor: PIC32MX Compiler: Microchip MPLAB XC32 v1.00 or higher Copyright © 2008-2009 released Microchip Technology Inc. All rights reserved. Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement). You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations. SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. *******************************************************************************/ //DOM-IGNORE-END #ifndef _ETH_H_ #define _ETH_H_ #include #include /* * WARNING: All the Peripheral Library (PLIB) functions, including those in this file, * will be removed from future releases of MPLAB XC32 C/C++ Compiler. * Please refer to the MPLAB Harmony Libraries for new projects. For legacy support, * these PLIB Libraries will be available for download from: www.microchip.com/pic32_peripheral_lib */ #ifndef _SUPPRESS_PLIB_WARNING #warning The PLIB functions and macros in this file will be removed from the MPLAB XC32 C/C++ Compiler in future releases #endif #ifdef _ETH // The Ethernet device is present // ***************************************************************************** // ***************************************************************************** // Section: Constants & Data Types // ***************************************************************************** // ***************************************************************************** // ***************************************************************************** /* Ethernet Operation Result Codes Summary: Defines the possible results of Ethernet operations that can succeed or fail Description: This enumeration defines the possible results of any of the Ethernet library operations that have the possibilty of failing. This result should be checked to ensure that the operation achieved the desired result. */ typedef enum { // Everything ok ETH_RES_OK, // Ethernet RX, TX, acknowledge packets: // No such packet exist ETH_RES_NO_PACKET, // Packet is queued (not transmitted or received and not processed) ETH_RES_PACKET_QUEUED, // Ethernet buffers, descriptors errors: // Some memory allocation failed ETH_RES_OUT_OF_MEMORY, // Not enough descriptors available ETH_RES_NO_DESCRIPTORS, // We don't support user space buffers. ETH_RES_USPACE_ERR, // The size of the receive buffers too small ETH_RES_RX_SIZE_ERR, // A received packet spans more buffers/descriptors than supplied ETH_RES_RX_PKT_SPLIT_ERR, // Negotiation errors: // No negotiation support ETH_RES_NEGOTIATION_UNABLE, // No negotiation active ETH_RES_NEGOTIATION_INACTIVE, // Negotiation not started yet ETH_RES_NEGOTIATION_NOT_STARTED, // Negotiation active ETH_RES_NEGOTIATION_ACTIVE, // Link down after negotiation, negotiation failed ETH_RES_NEGOTIATION_LINKDOWN, // PHY errors: // No Phy was detected or it failed to respond to reset command ETH_RES_DTCT_ERR, // No match between the capabilities: the Phy supported and the open // requested ones ETH_RES_CPBL_ERR, // Hardware configuration doesn't match the requested open mode ETH_RES_CFG_ERR, } eEthRes; // ***************************************************************************** /* Ethernet Open Configuration Settings Summary: Supported open configuration flags for the Ethernet module (EthMACOpen). Description: This enumeration defines the various configuration options for the Ethernet module. These values can be OR-ed together to create a configuration mask passed to the EthMACOpen routine. Remarks: When Auto negotiation is specified: - If multiple capability flags are set (ETH_OPEN_FDUPLEX, ETH_OPEN_HDUPLEX, ETH_OPEN_100, ETH_OPEN_10 ) they are all advertised as this link side capabilities. - If no setting is passed, the lowest one is taken, i.e. ETH_OPEN_HDUPLEX and ETH_OPEN_10. - Auto-MDIX requires Auto-Negotiation; ETH_OPEN_MDIX_NORM or ETH_OPEN_MDIX_SWAP setting irrelevant. When No Auto negotiation is specified: - If multiple settings, the highest priority setting is taken, i.e. ETH_OPEN_FDUPLEX over ETH_OPEN_HDUPLEX and ETH_OPEN_100 over ETH_OPEN_10. - If no setting, the lowest setting is taken, i.e. ETH_OPEN_HDUPLEX and ETH_OPEN_10. - The MDIX is set based on the ETH_OPEN_MDIX_NORM/ETH_OPEN_MDIX_SWAP setting. */ typedef enum { // Link capabilities flags: // Use auto negotiation. set the following flags to specify your choices ETH_OPEN_AUTO /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // Use full duplex or full duplex negotiation capability needed ETH_OPEN_FDUPLEX /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, // Use half duplex or half duplex negotiation capability needed ETH_OPEN_HDUPLEX /*DOM-IGNORE-BEGIN*/ = 0x4 /*DOM-IGNORE-END*/, // Use 100MBps or 100MBps negotiation capability needed ETH_OPEN_100 /*DOM-IGNORE-BEGIN*/ = 0x8 /*DOM-IGNORE-END*/, // Use 10MBps or 10MBps negotiation capability needed ETH_OPEN_10 /*DOM-IGNORE-BEGIN*/ = 0x10 /*DOM-IGNORE-END*/, // MAC flags: // Allow huge packets RX/TX ETH_OPEN_HUGE_PKTS /*DOM-IGNORE-BEGIN*/ = 0x20 /*DOM-IGNORE-END*/, // Loopbacked at the MAC level ETH_OPEN_MAC_LOOPBACK /*DOM-IGNORE-BEGIN*/ = 0x40 /*DOM-IGNORE-END*/, // When PHY is loopback-ed, negotiation will be disabled! ETH_OPEN_PHY_LOOPBACK /*DOM-IGNORE-BEGIN*/ = 0x80 /*DOM-IGNORE-END*/, // MDIX flags: // Use Auto MDIX ETH_OPEN_MDIX_AUTO /*DOM-IGNORE-BEGIN*/ = 0x100 /*DOM-IGNORE-END*/, // Use normal MDIX when Auto MDIX disabled ETH_OPEN_MDIX_NORM /*DOM-IGNORE-BEGIN*/ = 0x0 /*DOM-IGNORE-END*/, // Use swapped MDIX when Auto MDIX disabled ETH_OPEN_MDIX_SWAP /*DOM-IGNORE-BEGIN*/ = 0x200 /*DOM-IGNORE-END*/, // MII/RMII flags: // RMII connection ETH_OPEN_RMII /*DOM-IGNORE-BEGIN*/ = 0x400 /*DOM-IGNORE-END*/, // MII connection ETH_OPEN_MII /*DOM-IGNORE-BEGIN*/ = 0x000 /*DOM-IGNORE-END*/, // All capabilities default ETH_OPEN_DEFAULT = (ETH_OPEN_AUTO|ETH_OPEN_FDUPLEX|ETH_OPEN_HDUPLEX| ETH_OPEN_100|ETH_OPEN_10|ETH_OPEN_MDIX_AUTO) } eEthOpenFlags; // ***************************************************************************** /* Ethernet Link Status Codes Summary: Defines the possible status flags of Ethernet link. Description: This enumeration defines the flags describing the status of the Ethernet link. Remarks: Multiple flags can be set */ typedef enum { // No connection to the LinkPartner ETH_LINK_ST_DOWN /*DOM-IGNORE-BEGIN*/ = 0x0 /*DOM-IGNORE-END*/, // Link is up ETH_LINK_ST_UP /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // LP non negotiation able ETH_LINK_ST_LP_NEG_UNABLE /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, // LP fault during negotiation ETH_LINK_ST_REMOTE_FAULT /*DOM-IGNORE-BEGIN*/ = 0x4 /*DOM-IGNORE-END*/, // Parallel Detection Fault encountered (when ETH_LINK_ST_LP_NEG_UNABLE) ETH_LINK_ST_PDF /*DOM-IGNORE-BEGIN*/ = 0x8 /*DOM-IGNORE-END*/, // LP supports symmetric pause ETH_LINK_ST_LP_PAUSE /*DOM-IGNORE-BEGIN*/ = 0x10 /*DOM-IGNORE-END*/, // LP supports asymmetric TX/RX pause operation ETH_LINK_ST_LP_ASM_DIR /*DOM-IGNORE-BEGIN*/ = 0x20 /*DOM-IGNORE-END*/, // LP not there ETH_LINK_ST_NEG_TMO /*DOM-IGNORE-BEGIN*/ = 0x1000 /*DOM-IGNORE-END*/, // An unexpected fatal error occurred during the negotiation ETH_LINK_ST_NEG_FATAL_ERR /*DOM-IGNORE-BEGIN*/ = 0x2000 /*DOM-IGNORE-END*/, } eEthLinkStat; // ***************************************************************************** /* Ethernet Controller Status Codes Summary: Defines the possible status codes of Ethernet controller. Description: This enumeration defines the flags describing the status of the Ethernet controller. */ typedef enum { // A packet is currently received ETH_ST_RXBUSY /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // A packet is currently transmitted ETH_ST_TXBUSY /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, // Module is on or completing a transaction ETH_ST_BUSY /*DOM-IGNORE-BEGIN*/ = 0x4 /*DOM-IGNORE-END*/, } eEthStat; // ***************************************************************************** /* Ethernet Module Disable Summary: Defines the possible disable codes of Ethernet controller "EthClose" call. Description: This enumeration defines the close capabilities of the Ethernet module. */ typedef enum { // Wait for the current TX/RX op to finish ETH_CLOSE_GRACEFUL /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // Default close options ETH_CLOSE_DEFAULT = (0) } eEthCloseFlags; // ***************************************************************************** /* Ethernet MAC Pause Types Summary: Defines the possible Ethernet MAC pause types. Description: This enumeration defines the Ethernet MAC's pause capabilities. */ typedef enum { // No PAUSE capabilities ETH_MAC_PAUSE_TYPE_NONE /*DOM-IGNORE-BEGIN*/ = 0x0 /*DOM-IGNORE-END*/, // Supports symmetric PAUSE ETH_MAC_PAUSE_TYPE_PAUSE /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // Supports ASM_DIR ETH_MAC_PAUSE_TYPE_ASM_DIR /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, // The previous two values converted to TX/RX capabilities: // Enable MAC TX pause support ETH_MAC_PAUSE_TYPE_EN_TX /*DOM-IGNORE-BEGIN*/ = 0x4 /*DOM-IGNORE-END*/, // Enable MAC RX pause support ETH_MAC_PAUSE_TYPE_EN_RX /*DOM-IGNORE-BEGIN*/ = 0x8 /*DOM-IGNORE-END*/, // All types of pause ETH_MAC_PAUSE_ALL = (ETH_MAC_PAUSE_TYPE_PAUSE|ETH_MAC_PAUSE_TYPE_ASM_DIR| ETH_MAC_PAUSE_TYPE_EN_TX|ETH_MAC_PAUSE_TYPE_EN_RX), // All pause capabilities our MAC supports ETH_MAC_PAUSE_CPBL_MASK = ETH_MAC_PAUSE_ALL } eEthMacPauseType; // ***************************************************************************** // ***************************************************************************** // Section: Ethernet Peripheral Library Interface Routines // ***************************************************************************** // ***************************************************************************** // Section: Open and Configuration Functions /******************************************************************************* Function: eEthRes EthInit ( void ) Summary: Ethernet initialization routine Description: This function performs the initialization of the Ethernet Controller. Precondition: None. Parameters: None. Returns: ETH_RES_OK Example: EthInit(); Remarks: This function should be called before the EthMACOpen() routine. *****************************************************************************/ eEthRes EthInit ( void ); /******************************************************************************* Function: eEthRes EthClose( eEthCloseFlags cFlags ) Summary: Aborts any transactions and disables the Ethernet controller Description: This function performs an abort of any current Ethernet transactions, disables the Ethernet controller and interrupts. It should be called after the PHY close/reset procedure. Precondition: None. Parameters: cFlags - closing flags Returns: ETH_RES_OK Example: EthClose(ETH_CLOSE_DEFAULT); Remarks: It does not free any allocated memory. *****************************************************************************/ eEthRes EthClose ( eEthCloseFlags cFlags ); /******************************************************************************* Function: void EthMACOpen( eEthOpenFlags oFlags, eEthMacPauseType pauseType ) Summary: Initializes and configures the Ethernet MAC. Description: This function performs the open and configuration of the Ethernet MAC. It needs to be called after the EthInit() was called and the PHY initialized. Precondition: EthInit must have been called. Parameters: oFlags - Open flags pauseType - Pause type to be supported by the MAC Returns: Ethernet operation result code. Example: // Enable loopback at the MAC level oFlags = ETH_OPEN_FDUPLEX|ETH_OPEN_100|ETH_OPEN_HUGE_PKTS|ETH_OPEN_MAC_LOOPBACK; // Use both TX and RX pause type for Full Duplex pauseType = ETH_MAC_PAUSE_ALL; // Start the initialization sequence EthInit(); // Open and configure the MAC. // // Since we're not connected to an external PHY there's no negotiation // going on and we know all our opening flags EthMACOpen(oFlags, pauseType); Remarks: If no auto-negotiation is performed, the EthMACOpen() could be called immediately after EthInit() and PHY initialization. Otherwise the open flags and the pause type should be the ones obtained as a result of the PHY negotiation procedure! *****************************************************************************/ void EthMACOpen ( eEthOpenFlags oFlags, eEthMacPauseType pauseType ); /******************************************************************************* Function: void EthMACSetAddress ( unsigned char bAddress[6] ) Summary: Sets the MAC address Description: This function sets the MAC address. Precondition: None. Parameters: bAddress - standard MAC address, 6 bytes, Network order! Returns: None. Example: unsigned char hostAddress[6]= { 0x00, 0x04, 0xa3, 0x00, 0x00, 0x02}; EthMACSetAddress(hostAddress); Remarks: The default MAC address is loaded by the device at reset from the factory pre-programmed unique MAC address value. *****************************************************************************/ void EthMACSetAddress ( unsigned char bAddress[6] ); /******************************************************************************* Function: void EthMACGetAddress ( unsigned char bAddress[6] ) Summary: Returns the current MAC address Description: This function returns the current MAC address. Precondition: None. Parameters: bAddress - Address to store a standard MAC address, 6 bytes, Network order! Returns: None. Example: unsigned char currentMacAddress; EthMACGetAddress(¤tMacAddress); Remarks: *****************************************************************************/ void EthMACGetAddress ( unsigned char bAddress[6] ); /******************************************************************************* Function: void EthMACSetMaxFrame ( unsigned short maxFrmSz ) Summary: Sets the MAC maximum frame size Description: This function sets the MAC maximum frame size. Precondition: Should be called after EthInit(). Parameters: maxFrmSz - Maximum frame for the MAC to transmit or receive. Returns: None. Example: EthMACSetMaxFrame(0x800); Remarks: The default MAC frame size (0x600) is set by the EthInit() call. *****************************************************************************/ void EthMACSetMaxFrame ( unsigned short maxFrmSz ); // Section: Descriptors and Buffers Functions // ***************************************************************************** /* Ethernet Descriptor Allocation Function Pointer Function: void* ( size_t nitems, size_t size, void* param ) Summary: Pointer to a function that allocates the requested memory and returns a pointer to it. Description: Pointer to a function that allocates enough memory for "nitems" each of "size" bytes in length (total memory requested is nitems*size). The allocated space should be initialized to zero. Precondition: None Parameters: nitems - number of items to be allocated size - size of each item, in bytes param - extra parameter that will be used by the function call Returns: On success - A pointer to the requested space. On failure = A null pointer. Remarks: This function will be invoked for allocation of descriptors only. Therefore, the size parameter will be the one returned by EthDescriptorsGetSize(); */ typedef void* ( *pEthDcptAlloc )( size_t nitems, size_t size, void* param ); // ***************************************************************************** /* Ethernet Descriptor Free Function Function: void ( void* ptr, void* param ) Summary: Pointer to a function that deallocates the memory previously allocated by a pEthDcptAlloc function. Description: Pointer to a function that deallocates the memory previously allocated by a pEthDcptAlloc function. Precondition: The pEthDcptAlloc would have been previously called. Parameters: ptr - Points to the space that was previously allocated with a pEthDcptAlloc function. param - extra parameter that will be used by the function call Returns: None. Remarks: None. */ typedef void ( *pEthDcptFree ) ( void* ptr, void* param ); // ***************************************************************************** /* Ethernet Descriptor Types Summary: Enumeration defining the Ethernet descriptor types. Description: This enumeration defines the Ethernet descriptor types. Remarks: Most descriptor operations support just one type, but multiple flags can be set. */ typedef enum { // TX descriptor ETH_DCPT_TYPE_RX /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // RX descriptor ETH_DCPT_TYPE_TX /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, // All (both) types. Some descriptor operations support multiple types. ETH_DCPT_TYPE_ALL = (ETH_DCPT_TYPE_RX|ETH_DCPT_TYPE_TX) }eEthDcptType; // descriptor types // ***************************************************************************** /* Ethernet Descriptor Query Structure Summary: Structure used for a query of the Ethernet descriptors Description: This structure holds a snapshot of the current status of RX/TX descriptors. */ typedef struct { // The number of idle (unused) descriptors available in the TX/RX pool of descriptors. int dIdle; // The number of descriptors not acknowledged // Provides the number of descriptors that have valid transmitted/received packets // but haven't been acknowledged int dUnack; // The number of queued descriptors // Provides the number of descriptors that are just // queued for transmission (but not transmitted yet) or // receiving (but without a valid load). int dQueued; }sEthDcptQuery; // ***************************************************************************** /* Buffer Flags Summary: Flags for buffer attributes. Description: Some buffers can have special attributes, as defined by this enumeration. */ typedef enum { // The receive buffer is sticky, going to be used across multiple RX // operations once it's acknowledged ETH_BUFF_FLAG_RX_STICKY /*DOM-IGNORE-BEGIN*/ = 0x1 /*DOM-IGNORE-END*/, // The receive descriptor associated to this buffer should not be // automatically acknowledged when EthRxAcknowledgeBuffer/EthRxAcknowledgePacket // is called. // User is responsible for specifically calling EthAckRxDcpt() to acknowledge // the RX descriptor ETH_BUFF_FLAG_RX_UNACK /*DOM-IGNORE-BEGIN*/ = 0x2 /*DOM-IGNORE-END*/, } eEthBuffFlags; /******************************************************************************* Function: int EthDescriptorsPoolAdd ( int nDescriptors, eEthDcptType dType, pEthDcptAlloc fAlloc, void* fParam ) Summary: Adds transmit & receive descriptors to the pool. Description: This function adds the specified number of transmit/receive descriptors to the pool of descriptors. These descriptors are used whenever a new transmission or a reception is initiated. The needed memory per descriptor is returned by EthDescriptorsGetSize. Descriptors can be freed with EthDescriptorsPoolRemove. Precondition: EthInit should have been called. Parameters: nDescriptors - Number of descriptors to be added dType - TX/RX descriptors requested fAlloc - Function to be called to allocate the needed memory fParam - parameter to be used when fAlloc is called Returns: The number of descriptors successfully created. Example: if( EthDescriptorsPoolAdd(txDcptNo, ETH_DCPT_TYPE_TX, fMemAlloc, &myInstanceData) != txDcptNo ) { // Handle allocation error } Remarks: The number of created descriptors is different from the number of requested ones only if the memory allocation failed. The first time the specific pool is initialized an extra descriptor is added to the pool so that the actual memory requested will be (nDescriptors+1)*EthDescriptorsGetSize(). fAlloc should not be NULL. The complete clean-up is done by EthDescriptorsPoolCleanUp(); ETH_DCPT_TYPE_ALL use is invalid. A proper descriptor type (RX or TX) has to be used. *****************************************************************************/ int EthDescriptorsPoolAdd ( int nDescriptors, eEthDcptType dType, pEthDcptAlloc fAlloc, void* fParam ); /******************************************************************************* Function: int EthDescriptorsPoolRemove ( int nDescriptors, eEthDcptType dType, pEthDcptFree fFree, void* fParam ) Summary: Tries to remove the specified number of descriptors from the pool. Description: This function tries to remove the specified number of descriptors from the pool of transmit/receive descriptors. These descriptors that are NOT used at the time of call can be freed (i.e. the TX descriptors not queued for a transmission or the not busy RX descriptors). Precondition: EthInit should have been called. Parameters: nDescriptors - Number of descriptors to be removed dType - TX/RX descriptors requested fFree - Function to release the the memory fParam - parameter to be used when fFree is called Returns: The number of descriptors removed. Example: if ( EthDescriptorsPoolRemove(txDcptNo, ETH_DCPT_TYPE_TX, ffree, 0) != txDcptNo) { // Handle de-allocation error. } Remarks: If fFree is NULL then the descriptors are removed from the specified pool but no de-allocation function is called. The allocation/deallocation memory functions should be consistent. The complete clean-up is done by EthDescriptorsPoolCleanUp. ETH_DCPT_TYPE_ALL use is invalid. A proper descriptor type (RX or TX) has to be used. *****************************************************************************/ int EthDescriptorsPoolRemove ( int nDescriptors, eEthDcptType dType, pEthDcptFree fFree, void* fParam ); /******************************************************************************* Function: void EthDescriptorsPoolCleanUp ( eEthDcptType dType, pEthDcptFree fFree, void* fParam ) Summary: Removes all the specified descriptors from the pool. Description: This function performs descriptors clean-up and removes all the specified descriptors from the pool of transmit/receive descriptors. Precondition: EthClose should have been called. Parameters: dType - TX/RX/All descriptors requested fFree - Function to release the the memory fParam - parameter to be used when fFree is called Returns: None. Example: EthDescriptorsPoolCleanUp(ETH_DCPT_TYPE_ALL, fFree, &myInstanceData); Remarks: If fFree is NULL then the descriptors are removed from the pools but no de-allocation function is called. The allocation/deallocation memory functions should be consistent. It does not free the memory allocated for the application supplied "sticky" buffers. It is the calling application responsibility. EthClose should have been called or no TX/RX activity should be enabled at the time this function is called. If ETH_DCPT_TYPE_ALL is supplied the function will perform the clean-up of both types of descriptors. *****************************************************************************/ void EthDescriptorsPoolCleanUp ( eEthDcptType dType, pEthDcptFree fFree, void* fParam ); /******************************************************************************* Function: int EthDescriptorsGetSize ( eEthDcptType dType ) Summary: Returns the number of bytes needed for the storage of a descriptor. Description: This function returns the number of bytes needed for the storage of a descriptor in the transmit/receive engine. Precondition: None. Parameters: dType - TX/RX/All descriptors requested Returns: The size of a descriptor. Example: maxSize = EthDescriptorsGetSize(ETH_DCPT_TYPE_ALL); Remarks: If ETH_DCPT_TYPE_ALL supplied the function will return them size that accommodates both descriptors (maximum of the two values). *****************************************************************************/ int EthDescriptorsGetSize ( eEthDcptType dType ); /******************************************************************************* Function: void EthDescriptorsQuery ( eEthDcptType dType, sEthDcptQuery *pQuery ) Summary: Takes a snapshot of the current status of RX/TX descriptors. Description: This function takes a snapshot of the current status of RX/TX descriptors and provides the query result. Precondition: Parameters: dType - TX/RX descriptors requested pQuery - Address to store the result of the query See the sEthDcptQuery for details. Returns: None. Example: sEthDcptQuery queryResult; EthDescriptorsQuery(ETH_DCPT_TYPE_RX, &queryResult); Remarks: The returned numbers are info only. They can dynamically change. No protection against interrupts, multithreading, etc. ETH_DCPT_TYPE_ALL use is invalid. A proper descriptor type (RX or TX) has to be used. Whenever the automatic flow control is turned on, the reception will come to a halt once the number of unacknowledged RX descriptors (dUnack for query using ETH_DCPT_TYPE_RX) reaches 256. Also the number of currently received and unacknowledged descriptors control the behavior of the automatic flow control. See EthFCEnable for details. *****************************************************************************/ void EthDescriptorsQuery ( eEthDcptType dType, sEthDcptQuery *pQuery ); /******************************************************************************* Function: int EthDescriptorsGetRxUnack( void ) Summary: Provides the number of RX descriptors that are properly received and not acknowledged. Description: This function returns the number of RX descriptors that have been properly received by the receive engine and not acknowledged. These descriptors have to be acknowledged by software by calling EthRxAcknowledgePacket/EthRxAcknowledgeBuffer. Precondition: EthInit should have been called. Parameters: None. Returns: The number of RX descriptors that are currently unacknowledged. Example: if ( EthDescriptorsGetRxUnack()) >= 256 ) { // Handle RX halt } Remarks: Fast shortcut for getting the number of un-acknowledged RX descriptors. Whenever the automatic flow control is turned on, the reception will come to a halt once this number reaches 256. The number of currently received descriptors control the behavior of the automatic flow control. See EthFCEnable for details. *****************************************************************************/ int EthDescriptorsGetRxUnack ( void ); // DOM-IGNORE-BEGIN extern __inline__ int __attribute__((always_inline)) EthDescriptorsGetRxUnack( void ) { return ETHSTATbits.BUFCNT; } // DOM-IGNORE-END /******************************************************************************* Function: void* EthDescriptorGetBuffer ( void *pDcpt ) Summary: Returns the associated descriptor buffer. Description: This function returns the buffer currently associated with the specified descriptor. Precondition: Parameters: pDcpt - Pointer to a Ethernet Descriptor Returns: The address of the buffer associated with this descriptor or NULL if no such descriptor/buffer exists. Example: EthDescriptorsPoolRemove ( 1, ETH_DCPT_TYPE_RX, myRxFreeFnc, 0 ); void myRxFreeFnc( void* ptr, void* param) { void* pBuff = EthDescriptorGetBuffer(ptr); if(pBuff) { // De-allocate the associated buffer } } Remarks: The function is a helper that returns the buffer associated with a descriptor. It can be used to perform the queued RX/TX buffers clean-up since this list is maintained by the Ethernet library anyway. The pointer for a descriptor is returned by one of the EthDescriptorsPoolRemove() or EthDescriptorsPoolCleanUp() calls as the first parameter of the fFree function. No protection against interrupts, multithreading, etc. *****************************************************************************/ void* EthDescriptorGetBuffer ( void *pDcpt ); /******************************************************************************* Function: eEthRes EthRxBuffersAppend ( void *ppBuff[], int nBuffs, eEthBuffFlags rxFlags ) Summary: Supplies buffers to the receiving process and enables the receiving part of the controller. Description: This function supplies buffers to the receiving process and enables the receiving part of the controller. As soon as the controller starts receiving data packets these will be stored into memory at the addresses specified by these buffers. A received packet can consist of multiple buffers, split across buffers with the SAME size, as specified in the EthRxSetBufferSize. Each buffer needs an associated receive descriptor. Therefore, the number of needed receive descriptors should be available for this function to succeed. Once a receive operation is scheduled, EthRxGetPacket() can be called to get the received packet. Precondition: EthInit, EthDescriptorsPoolAdd, EthRxSetBufferSize should have been called. Each buffer supplied should be >= EthRxSetBufferSize(). Parameters: ppBuff - Pointer to an array of buffers (could be NULL terminated) to be appended to the receiving process nBuffs - Number of buffers supplied (or 0 if ppBuff is NULL terminated) rxFlags - Flags applied to all RX buffers passed Returns: ETH_RES_OK - success ETH_RES_NO_DESCRIPTORS - no enough RX descriptors ETH_RES_USPACE_ERR - buffers in user space not supported Example: ethRes = EthRxBuffersAppend(rxBuffers, rxDcptNo, ETH_BUFF_FLAG_RX_STICKY); if ( ethRes != ETH_RES_OK ) { // Handle error } Remarks: Not multithreaded safe. Don't call from from both ISR -non ISR code or multiple ISR's! This function enables the Ethernet receiving. When a packet is split into multiple buffers, all buffers have the same size, set by the EthRxSetBufferSize(). The append process continues until a NULL buffer pointer is retrieved or nBuffs buffers are appended. Only RX eEthBuffFlags are relevant for this function *****************************************************************************/ eEthRes EthRxBuffersAppend ( void *ppBuff[], int nBuffs, eEthBuffFlags rxFlags ); /******************************************************************************* Function: eEthRes EthRxSetBufferSize ( int rxBuffSize ) Summary: Sets the required buffer size for the receive operation. Description: This function sets the required buffer size for the receive operation. In this implementation, all receive descriptors use the same buffer size (unlike the transmission flow where each descriptor can have a different buffer size). Precondition: 0 < rxBuffSize <= 2032 rxBuffSize multiple of 16 Parameters: rxBuffSize - size of the RX buffers Returns: ETH_RES_OK - success ETH_RES_RX_SIZE_ERR - the requested size is invalid Example: EthRxSetBufferSize(rxBuffSize); Remarks: This function should be part of the initialization process and shoult NOT be called when the RX process is active! The receive buffer size is always TRUNCATED to a multiple of 16 bytes. *****************************************************************************/ eEthRes EthRxSetBufferSize ( int rxBuffSize ); // Section: TX/RX Functions // ***************************************************************************** /* Packet Descriptor Summary: Descriptor of a packet accepted by the TX/RX Ethernet engine. Description: A packet handled by the Ethernet TX/RX engine is a list of buffer descriptors. A packet consists of multiple buffers and each buffer needs a descriptor. Although the number of buffers per packet is not limited, note that the hardware overhead is higher when many buffers have to be handled for one packet. The list ends when the next field is NULL or when the pBuff is NULL. */ typedef struct _tag_sEthPktDcpt { // Next descriptor in chain. NULL to end struct _tag_sEthPktDcpt *next; // Buffer to be transmitted void *pBuff; // Number of bytes in the buffer 0-2047 allowed unsigned short int nBytes; } /*DOM-IGNORE-BEGIN*/ __attribute__ ((__packed__)) /*DOM-IGNORE-END*/ sEthPktDcpt; // ***************************************************************************** /* Transmitted Packet Status Summary: Status of a transmitted packet. Description: This structure contains the status of a transmitted packet. Notes: Status is always two "words" (64-bits) long. */ typedef union { struct { // Total bytes transmitted unsigned short totTxBytes; // Control frame transmitted unsigned txCtrl : 1; // Pause control frame transmitted unsigned txPause : 1; // Transmit backpressure applied unsigned txBPres : 1; // Transmit VLAN tagged frame unsigned txVLAN : 1; unsigned : 12; // Transmit bytes count unsigned short bCount; // Transmit collision count unsigned collCount : 4; // Transmit CRC error unsigned crcError : 1; // Tansmit length check error unsigned lenError : 1; // Tansmit length out of range unsigned lenRange : 1; // Transmit done unsigned txDone : 1; // Transmit multicast unsigned mcast : 1; // Transmit broadcast unsigned bcast : 1; // Transmit packet defer unsigned defer : 1; // Transmit excessive packet defer unsigned excDefer : 1; // Transmit maximum collision unsigned maxColl : 1; // Transmit late collision unsigned lateColl : 1; // Transmit giant frame (set when pktSz>MaxFrameSz && HugeFrameEn==0) unsigned giant : 1; // Transmit underrun unsigned underrun : 1; }__attribute__ ((__packed__)); // Status is 2 words always unsigned long long w; } sEthTxPktStat; // ***************************************************************************** /* Received Packet Status Summary: Status of a received packet. Description: This structure contains the status of a received packet. Notes: Status is always two "words" (64-bits) long. */ typedef union { struct { // Packet payload checksum unsigned pktChecksum :16; unsigned : 8; // Runt packet received unsigned runtPkt : 1; // Unicast, not me packet, unsigned notMeUcast : 1; // Hash table match unsigned htMatch : 1; // Magic packet match unsigned magicMatch : 1; // Pattern match match unsigned pmMatch : 1; // Unicast match unsigned uMatch : 1; // Broadcast match unsigned bMatch : 1; // Multicast match unsigned mMatch : 1; // Received bytes unsigned rxBytes :16; // Packet previously ignored unsigned prevIgnore : 1; // RX data valid event previously seen unsigned prevDV : 1; // Carrier event previously seen unsigned prevCarrier : 1; // RX code violation unsigned rxCodeViol : 1; // CRC error in packet unsigned crcError : 1; // Receive length check error unsigned lenError : 1; // Receive length out of range unsigned lenRange : 1; // Receive OK unsigned rxOk : 1; // Multicast packet unsigned mcast : 1; // Broadcast packet unsigned bcast : 1; // Dribble nibble unsigned dribble : 1; // Control frame received unsigned rxCtrl : 1; // Pause control frame received unsigned rxPause : 1; // Received unsupported code unsigned rxCodeErr : 1; // Received VLAN tagged frame unsigned rxVLAN : 1; unsigned : 1; }__attribute__ ((__packed__)); // Status is 2 words always unsigned long long w; } sEthRxPktStat; // ***************************************************************************** /* Ethernet Buffer Acknowledge Callback Function Function: void ( void *pPktBuff, int buffIx, void* param ) Summary: Pointer to an function called to acknowledge a buffer/packet. Description: Pointer to a function called to acknowledge the completion of a buffer/packet. Precondition: A TX or RX packet must have been queued. Parameters: pPktBuff - Pointer to the currently acknowledged transmitted or received buffer. buffIx - The 0-based buffer index for a packet that spans multiple buffers. param - extra parameter that will be used by the function call Returns: None. Remarks: This function is meant to be used for both RX and TX packets acknowledge. It allows the caller to pass an extra parameter that will be used in the function call. */ typedef void ( *pEthBuffAck ) ( void *pPktBuff, int buffIx, void* param ); /******************************************************************************* Function: eEthRes EthTxSendBuffer ( const void *pBuff, unsigned short int nBytes ) Summary: Schedules the supplied buffer for transmission Description: This function schedules the supplied buffer for transmission. To transmit this buffer an associated transmit descriptor is needed. Therefore, a transmit descriptor should be available for this function to succeed. Once a transmission is scheduled and done, EthTxGetBufferStatus can be called to check the transmission result. Precondition: EthMACOpen, EthDescriptorsPoolAdd should have been called. Valid buffer pointer required. Buffers specified should be > 0 and < 2048 bytes in size. Parameters: pBuff - Adress of buffer to be sent nBytes - Size of the buffer in bytes Returns: ETH_RES_OK - success ETH_RES_NO_DESCRIPTORS - no descriptors available ETH_RES_USPACE_ERR - user space buffers not supported Example: EthTxSendBuffer(txBuffer, pktSize); Remarks: Not multithreaded safe. Don't call from from both ISR and non ISR code or multiple ISR's! This function enables the Ethernet transmission. This function is for transmission of packets completely assembled in one buffer. *****************************************************************************/ eEthRes EthTxSendBuffer ( const void *pBuff, unsigned short int nBytes ); /******************************************************************************* Function: eEthRes EthTxSendPacket ( const sEthPktDcpt *pPkt ) Summary: Schedules the supplied packet for transmission. Description: This function schedules the supplied packet for transmission. Each packet can consist of multiple buffers, each having a different size, as specified in the packet descriptor. Each buffer will need an associated transmit descriptor. Therefore, the number of needed transmit descriptors should be available for this function to succeed. Once a transmission is scheduled and done, EthTxGetPacketStatus can be called to check the transmission result. Precondition: EthMACOpen, EthDescriptorsPoolAdd should have been called. Valid packet descriptor pointer required. Buffers specified should be >0 and < 2048 bytes in size. Parameters: pPkt - Packet descriptor consisting of a list of buffer descriptors, terminated by a NULL pointer. Returns: ETH_RES_OK - success ETH_RES_NO_DESCRIPTORS - no descriptors available ETH_RES_USPACE_ERR - user space buffers not supported Example: ethRes = EthTxSendPacket(&txDcpt); if ( ethRes != ETH_RES_OK ) { // Transmission failed } Remarks: Not multithreaded safe. Don't call from from both ISR and non-ISR code or multiple ISR's! This function enables the Ethernet transmission. The packet construction from buffers stops when a descriptor with NULL buffer or 0 size is retrieved or the list ends. *****************************************************************************/ eEthRes EthTxSendPacket ( const sEthPktDcpt *pPkt ); /******************************************************************************* Function: eEthRes EthTxGetBufferStatus ( const void *pBuff, const sEthTxPktStat **pTxStat ) Summary: Provides the status of a transmitted buffer/packet. Description: This function provides the status of a transmitted buffer/packet. The transmission of this packet has to have been completed otherwise the call will fail. Precondition: EthTxSendBuffer/EthTxSendPacket should have been called and the pBuff pointer must be valid. Parameters: pBuff - Buffer part of the packet whose status is being queried. pTxStat - Address to store the pointer to the packet status or NULL if status not needed Returns: ETH_RES_OK - the packet was transmitted OK, ETH_RES_PACKET_QUEUED - the packet is not done yet ETH_RES_NO_PACKET - no such packet exists Example: ethRes = EthTxGetBufferStatus(pTxBuff, NULL); if ( ethRes != ETH_RES_OK ) { // Handle packet not transmitted } Remarks: The returned pointer to the packet status is invalid after the EthTxAcknowledgeBuffer/EthTxAcknowledgePacket is called. pBuff must be the pointer to the first buffer in the packet, if the packet spans multiple buffers. *****************************************************************************/ eEthRes EthTxGetBufferStatus ( const void *pBuff, const sEthTxPktStat **pTxStat ); /******************************************************************************* Function: eEthRes EthTxGetPacketStatus(const sEthPktDcpt* pPkt, const sEthTxPktStat** pTxStat) Summary: Provides the status of a transmitted packet. Description: This function provides the status of a transmitted packet. The transmission of this packet has to have been completed otherwise the call will fail. Precondition: EthTxSendPacket should have been called and the pPkt pointer must be valid. Parameters: pPkt - Packet whose status is being queried. pTxStat - Address to store the pointer to the packet status or NULL if status not needed Returns: ETH_RES_OK - the packet was transmitted OK, ETH_RES_PACKET_QUEUED - the packet is not done yet ETH_RES_NO_PACKET - no such packet exists Example: ethRes = EthTxGetPacketStatus(pTxPacket, NULL); if ( ethRes != ETH_RES_OK ) { // Handle packet not transmitted } Remarks: The returned pointer to the packet status is invalid after the EthTxAcknowledgeBuffer/EthTxAcknowledgePacket is called. *****************************************************************************/ eEthRes EthTxGetPacketStatus(const sEthPktDcpt* pPkt, const sEthTxPktStat** pTxStat); // DOM-IGNORE-BEGIN extern __inline__ eEthRes __attribute__((always_inline)) EthTxGetPacketStatus(const sEthPktDcpt* pPkt, const sEthTxPktStat** pTxStat) { return EthTxGetBufferStatus(pPkt?pPkt->pBuff:0, pTxStat); } // DOM-IGNORE-END /******************************************************************************* Function: eEthRes EthTxAcknowledgeBuffer ( const void *pBuff, pEthBuffAck ackFnc, void* fParam ) Summary: Acknowledges a transmitted buffer/packet Description: This function acknowledges a transmitted buffer/packet. The transmission of this packet has to have been completed otherwise the call will fail. When pBuff==NULL, all currently transmitted packets will be acknowledged. The ackFnc, if !NULL, will be called for each buffer within the packet in turn. Precondition: EthTxSendBuffer/EthTxSendPacket should have been called. Parameters: pBuff - Buffer of the packet to be acknowledged or NULL. ackFnc - Function to be called for the acknowledged buffers or NULL fParam - Parameter to be used in the ackFnc callback Returns: ETH_RES_OK - Success ETH_RES_PACKET_QUEUED - The packet is scheduled for transmission/ There are packets scheduled to be transmitted ETH_RES_NO_PACKET - No such packet exists in the transmit queue/ No packets scheduled for transmit Example: ethRes=EthTxAcknowledgeBuffer(pTxBuff, myAckFnc, &myInstanceData); void myAckFnc(void* pBuff, int buffIx, void* param) { myInstanceType* pType=(myInstanceType*)param; // Handle each buffer acknowledgement } Remarks: Any transmitted packet has to be acknowledged, otherwise the Ethernet library will run out of transmission descriptors. pBuff must be the pointer to the first buffer in the packet, if the packet spans multiple buffers. ackFnc is just a helper that allows the application to acknowledge the transmitted buffers without the need to maintain a list of buffers scheduled for transmission (this list is maintained by the Ethernet library anyway). Useful especially when the transmission result is not really needed and the function is called with pBuff=0. *****************************************************************************/ eEthRes EthTxAcknowledgeBuffer ( const void *pBuff, pEthBuffAck ackFnc, void* fParam ); /******************************************************************************* Function: eEthRes EthTxAcknowledgePacket(const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ) Summary: Acknowledges a transmitted packet Description: This function acknowledges a transmitted packet. The transmission of this packet has to have been completed otherwise the call will fail. When pPkt==NULL, all currently transmitted packets will be acknowledged. The ackFnc, if !NULL, will be called for each buffer within the packet in turn. Precondition: EthTxSendPacket should have been called. Parameters: pPkt - Packet to be acknowledged or NULL. ackFnc - Function to be called to acknowledge each buffer within the packet or NULL fParam - Parameter to be used in the ackFnc callback Returns: ETH_RES_OK - Success ETH_RES_PACKET_QUEUED - The packet is queued for transmission/ There are packets scheduled to be transmitted ETH_RES_NO_PACKET - No such packet exist sin th etransmit queue/ No packets scheduled for transmit Example: ethRes=EthTxAcknowledgePacket(pTxPkt, 0, 0); Remarks: Any transmitted packet has to be acknowledged, otherwise the Ethernet library will run out of transmission descriptors. ackFnc is just a helper that allows the application to acknowledge the transmitted buffers without the need to maintain a list of buffers scheduled for transmission (this list is maintained by the Ethernet library anyway). Useful especially when the transmission result is not really needed and the function is called with pPkt=0. *****************************************************************************/ eEthRes EthTxAcknowledgePacket(const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ); // DOM-IGNORE-BEGIN extern __inline__ eEthRes __attribute__((always_inline)) EthTxAcknowledgePacket(const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ) { return EthTxAcknowledgeBuffer(pPkt?pPkt->pBuff:0, ackFnc, fParam); } // DOM-IGNORE-END /******************************************************************************* Function: eEthRes EthRxGetBuffer ( void **ppBuff, const sEthRxPktStat **pRxStat ) Summary: Returns a pointer to the data and the status of the next available received packet. Description: This function returns a pointer to the data and the status of the next available received packet. If there's no available fully received packet the call will fail (ETH_RES_PACKET_QUEUED/ETH_RES_NO_PACKET). If the received packet spans multiple buffers/descriptors (i.e. when the size of the buffer, EthRxSetBufferSize() is less than the packet size) ETH_RES_RX_PKT_SPLIT_ERR will be returned. However, if the ppBuff is NULL, then the caller can use the returned pRxStat to check the total size of the packet. Then using the size of the set buffers, the number of buffers used in the packet will result. Precondition: EthRxSetBufferSize, EthRxBuffersAppend should have been called. Parameters: ppBuff - Address of a pointer to packet buffer data or NULL pRxStat - Address to store the pointer to the packet status or NULL Returns: ETH_RES_OK - For success ETH_RES_PACKET_QUEUED - The packet is in the reception queus/ There are packets queued for receive but not completed yet ETH_RES_NO_PACKET - No such packet is in the receiving queue/ No packets available in the receiving queue ETH_RES_RX_PKT_SPLIT_ERR - Packet spans accross multiple buffers Example: // Wait to receive a packet do { ethRes = EthRxGetBuffer(&pBuff, &pRxPktStat); } while ( ethRes == ETH_RES_PACKET_QUEUED ); Remarks: The returned status pointer is invalid once the EthRxAcknowledgeBuffer/EthRxAcknowledgePacket is called. Also the associated packet buffer if it was appended with a ETH_BUFF_FLAG_RX_STICKY flag. The returned buffer, if existent, will be marked as reported only when the result returned is ETH_RES_OK. In this case a new call to the function will not return the same buffer. If the call failed for some reason (result!=ETH_RES_OK) the returned buffer is not marked as reported. A new call to this function will return the same buffer. *****************************************************************************/ eEthRes EthRxGetBuffer ( void **ppBuff, const sEthRxPktStat **pRxStat ); /******************************************************************************* Function: eEthRes EthRxGetPacket ( sEthPktDcpt *pPkt, int *pnBuffs, const sEthRxPktStat **pRxStat ) Summary: Provides the layout and the status of the next available received packet. Description: This function returns the layout and the status of the next available received packet. If there's no available fully received packet the call will fail (ETH_RES_PACKET_QUEUED/ETH_RES_NO_PACKET). The supplied pPkt has to be large enough to accommodate the packet layout in the case of packets split across multiple buffers/descriptors (i.e. when the size of the buffer, EthRxSetBufferSize() is less than the packet size) otherwise ETH_RES_RX_PKT_SPLIT_ERR will be returned. However, if the pPkt is NULL, then the caller can use the returned pRxStat to check the total size of the packet. Then using the size of the set buffers, the number of buffers in pPkt will result. pnBuffs can be used for the same purpose. If pnBuffs is supplied, the numbers of buffers in the packet will be returned. Precondition: EthRxSetBufferSize, EthRxBuffersAppend should have been called. Parameters: pPkt - Pointer to a packet descriptor: a list of buffer descriptors large enough to receive the packet layout or NULL. pnBuffs - Pointer to store the number of buffers in the packet or NULL. pRxStat - Address to store the pointer to the packet status or NULL. Returns: ETH_RES_OK - For success. ETH_RES_PACKET_QUEUED - The packet is queued for reception/ There are packets queued for receive but not completed yet. ETH_RES_NO_PACKET - No such packet in the receiving queue/ No packets available in the receiving queue. ETH_RES_RX_PKT_SPLIT_ERR - Packet descriptor not large enough to store the whole packet. Example: // Wait to receive a packet do { ethRes = EthRxGetPacket(&rxPktDcpt, &buffsPerRxPkt, &pRxPktStat); } while ( ethRes== ETH_RES_PACKET_QUEUED ); Remarks: The packet list, when supplied, is terminated with a NULL buffer The returned status pointer is invalid after the EthRxAcknowledgePacket() is called. Also any buffers that were appended with a ETH_BUFF_FLAG_RX_STICKY flag associated to the packet buffers. The returned packet, if existent, will be marked as reported only when the result returned is ETH_RES_OK. In this case a new call to the function will not return the same packet. If the call failed for some reason (result!=ETH_RES_OK) the returned packet is not marked as reported. A new call to this function will return the same packet. *****************************************************************************/ eEthRes EthRxGetPacket ( sEthPktDcpt *pPkt, int *pnBuffs, const sEthRxPktStat **pRxStat ); /******************************************************************************* Function: eEthRes EthRxAcknowledgeBuffer ( const void *pBuff, pEthBuffAck ackFnc, void* fParam ) Summary: Acknowledges a received buffer/packet. Description: This function acknowledges a received buffer/packet. The supplied packet has to have been previously received otherwise the call will fail. When pBuff==NULL, all currently received packets will be acknowledged. The ackFnc, if !NULL, will be called for each buffer within the packet in turn. Precondition: EthRxSetBufferSize, EthRxBuffersAppend, EthRxGetPacket should have been called. Parameters: pBuff - Buffer/packet to be acknowledged or NULL ackFnc - Function to be called for the acknowledged buffers or NULL fParam - Parameter to be used in the ackFnc callback Returns: ETH_RES_OK - Success ETH_RES_PACKET_QUEUED - The packet is in the receiving queue/ There are packets in the receiving queue ETH_RES_NO_PACKET - No such packet in the receiving queue/ No packets available in the receiving queue Example: ethRes = EthRxAcknowledgeBuffer(pRxBuff, myAckFnc, &myInstanceData); if ( ethRes != ETH_RES_OK ) { // Handle buffer not acknowledged } void myAckFnc(void* pBuff, int buffIx, void* param) { myInstanceType* pType=(myInstanceType*)param; // Handle each buffer acknowledgement } Remarks: Any received packet has to be acknowledged, otherwise the Ethernet library will run out of descriptors. pBuff must be the pointer to the first buffer in the packet, if the packet spans multiple buffers. ackFnc is just a helper that allows the application to call an acknowledge function for each received buffer in turn. *****************************************************************************/ eEthRes EthRxAcknowledgeBuffer ( const void *pBuff, pEthBuffAck ackFnc, void* fParam ); /******************************************************************************* Function: eEthRes EthRxAcknowledgePacket ( const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ) Summary: Acknowledges a received packet. Description: This function acknowledges a received packet. The supplied packet has to have been previously received otherwise the call will fail. When pPkt==NULL, all currently received packets will be acknowledged. The ackFnc, if !NULL, will be called for each buffer within the packet in turn. Precondition: EthRxSetBufferSize, EthRxBuffersAppend, EthRxGetPacket should have been called. Parameters: pPkt - Packet to be acknowledged or NULL ackFnc - Function to be called for the each buffer within the packet or NULL fParam - Parameter to be used in the ackFnc callback Returns: ETH_RES_OK - Success ETH_RES_PACKET_QUEUED - The packet is in the receiving queue/ There are packets in the receiving queue ETH_RES_NO_PACKET - No such packet in the receiving queue/ No packets available in the receiving queue Example: ethRes = EthRxAcknowledgePacket(pRxPkt, NULL, 0); if ( ethRes != ETH_RES_OK ) { // Handle packet not acknowledged } Remarks: Any received packet has to be acknowledged, otherwise the Ethernet library will run out of descriptors. ackFnc is just a helper that allows the application to call an acknowledge function for each received buffer in turn. *****************************************************************************/ eEthRes EthRxAcknowledgePacket ( const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ); // DOM-IGNORE-BEGIN extern __inline__ eEthRes __attribute__((always_inline)) EthRxAcknowledgePacket(const sEthPktDcpt* pPkt, pEthBuffAck ackFnc, void* fParam ) { return EthRxAcknowledgeBuffer(pPkt?pPkt->pBuff:0, ackFnc, fParam); } // DOM-IGNORE-END // Section: Status Functions /******************************************************************************* Function: eEthStat EthStatusGet ( void ) Summary: Returns the current controller status. Description: This function returns the current controller status. Precondition: None. Parameters: None. Returns: Current Ethernet controller status. Example: ethStat = EthStatusGet(); Remarks: None. *****************************************************************************/ eEthStat EthStatusGet ( void ); // Section: Flow Control Functions // ***************************************************************************** /* Ethernet Flow Control Summary: Defines the possible Ethernet flow control types. Description: This enumeration defines the Ethernet flow control types. */ typedef enum { // Auto flow control ETH_FC_AUTO = 0, // Software flow control ETH_FC_SOFTWARE } eEthFc; /******************************************************************************* Function: void EthFCSetPauseValue ( unsigned int pauseBytes ) Summary: Sets the pause value to be used with manual or auto flow control. Description: This function sets the pause value to be used with manual or auto flow control. The pause time is calculated as being the time needed to transmit pauseBytes bytes. Precondition: EthInit should have been called. 64 < pauseBytes < 4194304 Parameters: pauseBytes - The number of bytes to pause Returns: None. Example: EthFCSetPauseValue(128); Remarks: The pauseBytes value is relevant for full duplex mode only. In half duplex, back pressure is applied. Should be called only when receive is not enabled (i.e. before EthRxBuffersAppend() is called, for example). *****************************************************************************/ void EthFCSetPauseValue ( unsigned int pauseBytes ); /******************************************************************************* Function: void EthFCEnable ( eEthFc fcType, int enable ) Summary: Enables or disables selected flow control. Description: When enabling software flow control: * In full duplex mode, this function immediately enables the manual flow control and sends a pause frame with the desired pause time. * Further on, a pause frame is resent, every interval corresponding to pause time/2. * In half duplex mode, back pressure is applied. When disabling software flow control: * In full duplex, this function immediately disables the manual flow control and sends a pause frame with the pause time set to 0. * In half duplex, the back pressure is removed. When enabling the auto flow control: * As soon as the number of the unacknowledged received descriptors ( BUFCNT = EthDescriptorsGetRxUnack() ) becomes >= fullWM: * In full duplex mode a pause frame is sent with the specified pause time (EthFCSetPauseValue). * Further on, a pause frame is resent, every interval corresponding to pause time/2. * In half duplex mode, back pressure is applied. * As soon as the BUFCNT becomes = emptyWM: * In full duplex mode a pause frame is sent with the pause value set to 0. * In half duplex mode, the back pressure is removed. * When disabling auto flow control: * In full duplex, this function immediately disables the flow control and sends a pause frame with the pause time set to 0. * In half duplex, the back pressure is removed. Precondition: EthInit, EthFCSetPauseValue should have been called. Parameters: fcType - Type of the flow control desired: auto or software (manual) enable - Boolean to enable/disable the flow control Returns: None. Example: EthFCEnable(ETH_FC_AUTO, 1); Remarks: BUFCNT is decremented by a call to EthRxAcknowledgePacket/EthRxAcknowledgeBuffer. *****************************************************************************/ void EthFCEnable ( eEthFc fcType, int enable ); /******************************************************************************* Function: void EthFCSetRxWMark ( int fullWM, int emptyWM ) Summary: Sets the automatic flow control watermarks. Description: This function sets the values for the watermarks used in the automatic flow control. Precondition: EthInit, should have been called. 0 <= emptyWM < fullWM < 256 Parameters: fullWM - The full watermark value emptyWM - The empty watermark value Returns: None. Example: EthFCSetRxWMark(4, 64); Remarks: See the description of the automatic flow control in the EthFCEnable description. To take into account the delays inherent to the traffic stop, the value for fullWM should be set in such a way that the automatic flow control kicks in when there's less than 3 frames (3*1536 bytes) available in the receive descriptors. *****************************************************************************/ void EthFCSetRxWMark ( int fullWM, int emptyWM ); // Section: RX Filtering Functions // ***************************************************************************** /* Ethernet Receive Filter Flags Summary: Defines the receive filter flags Description: This enumeration defines the receive filter flags. Remarks: Multiple values can be OR-ed together. The values in this enumeration are displayed in the order of priority that the receive filter state machine works, with the highest priority first. Once a filter accepts or rejects a packet, further filters are not tried. If a packet isn't rejected/accepted after all filters are tried, it will be rejected by default! */ typedef enum { // Frames with wrong CRC are accepted ETH_FILT_CRC_ERR_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_CRCERREN_MASK /*DOM-IGNORE-END*/, // Runt frames accepted ETH_FILT_RUNT_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_RUNTERREN_MASK /*DOM-IGNORE-END*/, // Frames with wrong CRC are rejected ETH_FILT_CRC_ERR_REJECT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_CRCOKEN_MASK /*DOM-IGNORE-END*/, // Runt frames rejected ETH_FILT_RUNT_REJECT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_RUNTEN_MASK /*DOM-IGNORE-END*/, // Me unicast accepted ETH_FILT_ME_UCAST_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_UCEN_MASK /*DOM-IGNORE-END*/, // Not me unicast accepted ETH_FILT_NOTME_UCAST_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_NOTMEEN_MASK /*DOM-IGNORE-END*/, // Multicast accepted ETH_FILT_MCAST_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_MCEN_MASK /*DOM-IGNORE-END*/, // Broadcast accepted ETH_FILT_BCAST_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_BCEN_MASK /*DOM-IGNORE-END*/, // Hash table matches destination address accepted ETH_FILT_HTBL_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_HTEN_MASK /*DOM-IGNORE-END*/, // Magic packet accepted ETH_FILT_MAGICP_ACCEPT /*DOM-IGNORE-BEGIN*/ = _ETHRXFC_MPEN_MASK /*DOM-IGNORE-END*/, // All Filters ETH_FILT_ALL_FILTERS = ETH_FILT_CRC_ERR_ACCEPT | ETH_FILT_RUNT_ACCEPT | ETH_FILT_CRC_ERR_REJECT | ETH_FILT_RUNT_REJECT | ETH_FILT_ME_UCAST_ACCEPT | ETH_FILT_NOTME_UCAST_ACCEPT | ETH_FILT_MCAST_ACCEPT | ETH_FILT_BCAST_ACCEPT | ETH_FILT_HTBL_ACCEPT | ETH_FILT_MAGICP_ACCEPT } eEthRxFilters; // ***************************************************************************** /* Ethernet Pattern Match Modes Summary: Defines pattern match modes Description: This enumeration defines the Ethernet pattern match modes. Remarks: These are mutually exclusive modes, not flags. However, ETH_FILT_PMATCH_INVERT act as a flag and can be applied to any value. */ typedef enum { // Simple Pattern Match accepted ETH_FILT_PMATCH_ACCEPT = 1, // Pattern Match AND destination==me ETH_FILT_PMATCH_ME_UCAST_ACCEPT, // Pattern Match AND destination!=me ETH_FILT_PMATCH_NOTME_UCAST_ACCEPT, // Pattern Match AND destination!=unicast ETH_FILT_PMATCH_MCAST_ACCEPT, // Pattern Match AND destination==unicast ETH_FILT_PMATCH_NOT_MCAST_ACCEPT, // Pattern Match AND destination==broadcast ETH_FILT_PMATCH_BCAST_ACCEPT, // Pattern Match AND destination!=broadcast ETH_FILT_PMATCH_NOT_BCAST_ACCEPT, // Pattern Match AND hash table filter match (irrespective of the // ETH_FILT_HTBL_ACCEPT setting) ETH_FILT_PMATCH_HTBL_ACCEPT, // Pattern Match AND packet ==magic packet ETH_FILT_PMATCH_MAGICP_ACCEPT, // If set, the pattern must NOT match for a successful Pattern Match to // occur! ETH_FILT_PMATCH_INVERT = 0x80000000 } eEthPMatchMode; /******************************************************************************* Function: void EthRxFiltersSet ( eEthRxFilters rxFilters ) Summary: Sets the acceptance/rejection filters for the Ethernet receive. Description: This function sets the acceptance/rejection filters for the Ethernet receive mechanism. Multiple filters can be OR-ed together. All filter specified in rxFilters will be set. Precondition: This function should not be called when Ethernet RX operation is enabled. Parameters: rxFilters - RX filters that are to be set Returns: None. Example: EthRxFiltersSet(ETH_FILT_CRC_ERR_REJECT | ETH_FILT_RUNT_REJECT | ETH_FILT_ME_UCAST_ACCEPT| ETH_FILT_MCAST_ACCEPT | ETH_FILT_BCAST_ACCEPT | ETH_FILT_NOTME_UCAST_ACCEPT); Remarks: All filters except Pattern Match can be set. Use EthRxFiltersPMSet(). Before enabling the Hash Table filter, the hash table values should be set using EthRxFiltersHTSet(). See the definition of the eEthRxFilters for the priority of the RX filters. *****************************************************************************/ void EthRxFiltersSet ( eEthRxFilters rxFilters ); /******************************************************************************* Function: void EthRxFiltersClr ( eEthRxFilters rxFilters ) Summary: Clears the acceptance/rejection filters for the Ethernet receive. Description: This function clears the acceptance/rejection filters for the Ethernet receive mechanism. Multiple filters can be OR-ed together. All filters specified in rxFilters will be cleared. Precondition: This function should not be called when Ethernet RX operation is enabled. Parameters: rxFilters - RX filters that are to be cleared Returns: None. Example: EthRxFiltersClr(ETH_FILT_ALL_FILTERS); Remarks: All filters except Pattern Match can be cleared. Use EthRxFiltersPMClr(); *****************************************************************************/ void EthRxFiltersClr ( eEthRxFilters rxFilters ); /******************************************************************************* Function: void EthRxFiltersWrite ( eEthRxFilters rxFilters ) Summary: Updates the acceptance/rejection filters for the Ethernet receive. Description: This function updates the acceptance/rejection filters for the Ethernet receive mechanism to the required value. Precondition: This function should not be called when Ethernet RX operation is enabled. Parameters: rxFilters - RX filters that are to be written Returns: None. Example: EthRxFiltersWrite(ETH_FILT_ALL_FILTERS); Remarks: All filters except Pattern Match can be updated. The Pattern Match filter will be disabled by this call. Use EthRxFiltersPMSet(); Before enabling the Hash Table filter, the hash table values should be set using EthRxFiltersHTSet(). See the definition of the eEthRxFilters for the priority of the RX filters. *****************************************************************************/ void EthRxFiltersWrite ( eEthRxFilters rxFilters ); /******************************************************************************* Function: void EthRxFiltersHTSet ( unsigned long long htable ) Summary: Sets the hash table for the hash table RX filter. Description: This function sets the hash table for the hash table RX filter. Precondition: This function should not be called when Ethernet RX operation is enabled and the hash filter is active. Parameters: htable - The hash table itself Returns: None. Example: Remarks: Properly set the hash table with this function before enabling the Hash Table filter. *****************************************************************************/ void EthRxFiltersHTSet ( unsigned long long htable ); /******************************************************************************* Function: void EthRxFiltersPMSet ( eEthPMatchMode mode, unsigned long long matchMask, unsigned int matchOffs, unsigned int matchChecksum ) Summary: Enables the Pattern Match filter with the specified settings. Description: This function enables the Pattern Match filter with the specified settings for the offset and window mask. The calculated checksum of the 64 bytes window starting at matchOffs and using the matchMask bytes in the window, is compared against matchChecksum. If ETH_FILT_PMATCH_INVERT is used in the mode, then the calculated checksum must not match the passed matchChecksum in order for the Pattern Match to succeed. Precondition: This function should not be called when Ethernet RX operation is enabled. Parameters: mode - The required Pattern Match Mode matchMask - Mask in the 64 byte window matchOffs - The offset applied to the incoming data (0 to 8128) matchChecksum - The 16 bit checksum used for comparison Returns: Example: EthRxFiltersPMSet(ETH_FILT_PMATCH_ACCEPT, MY_PATTERN, 0, MY_CHECKSUM); Remarks: None. *****************************************************************************/ void EthRxFiltersPMSet ( eEthPMatchMode mode, unsigned long long matchMask, unsigned int matchOffs, unsigned int matchChecksum ); /******************************************************************************* Function: void EthRxFiltersPMClr ( void ) Summary: Disables the Pattern Match receive filter. Description: This function disables the Pattern Match receive filter. Precondition: This function should not be called when Ethernet RX operation is enabled. Parameters: None. Returns: None. Example: EthRxFiltersPMClr(); Remarks: None. *****************************************************************************/ void EthRxFiltersPMClr ( void ); // Section: Ethernet Event Functions // ***************************************************************************** /* Ethernet Event Flags Summary: Ethernet event flags Description: This enumeration defines flags for the possible Ethernet events that can cause interrupts. */ typedef enum { // RX FIFO overflow ETH_EV_RXOVFLOW /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_RXOVFLW_MASK /*DOM-IGNORE-END*/, // RX buffer not available (descriptor overrun) ETH_EV_RXBUFNA /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_RXBUFNA_MASK /*DOM-IGNORE-END*/, // TX abort condition ETH_EV_TXABORT /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_TXABORT_MASK /*DOM-IGNORE-END*/, // TX done ETH_EV_TXDONE /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_TXDONE_MASK /*DOM-IGNORE-END*/, // RX activity ETH_EV_RXACT /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_RXACT_MASK /*DOM-IGNORE-END*/, // RX packet pending ETH_EV_PKTPEND /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_PKTPEND_MASK /*DOM-IGNORE-END*/, // RX packet successfully received ETH_EV_RXDONE /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_RXDONE_MASK /*DOM-IGNORE-END*/, // Full watermark reached ETH_EV_FWMARK /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_FWMARK_MASK /*DOM-IGNORE-END*/, // Empty watermark reached ETH_EV_EWMARK /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_EWMARK_MASK /*DOM-IGNORE-END*/, // RX bus error ETH_EV_RXBUSERR /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_RXBUSE_MASK /*DOM-IGNORE-END*/, // TX bus error ETH_EV_TXBUSERR /*DOM-IGNORE-BEGIN*/ = _ETHIRQ_TXBUSE_MASK /*DOM-IGNORE-END*/, // All events ETH_EV_ALL = (ETH_EV_RXOVFLOW | ETH_EV_RXBUFNA | ETH_EV_TXABORT | ETH_EV_TXDONE | ETH_EV_RXACT | ETH_EV_PKTPEND | ETH_EV_RXDONE | ETH_EV_FWMARK | ETH_EV_EWMARK | ETH_EV_RXBUSERR | ETH_EV_TXBUSERR) } eEthEvents; /******************************************************************************* Function: void EthEventsEnableSet ( eEthEvents eEvents ) Summary: Enables the events that will generate interrupts for the Ethernet controller. Description: The function enables the events that will generate interrupts for the Ethernet controller. Multiple events can be OR-ed together. Any event that is set in the eEvents will be enabled , the other events won't be touched. Precondition: None. Parameters: eEvents - Events with the significance described in the eEthEvents definition. Returns: None. Example: EthEventsEnableSet(ETH_EV_ALL); Remarks: None. *****************************************************************************/ void EthEventsEnableSet ( eEthEvents eEvents ); /******************************************************************************* Function: void EthEventsEnableClr ( eEthEvents eEvents ) Summary: Disables the events that will generate interrupts. Description: The function disables the events that will generate interrupts for the Ethernet controller. Multiple events can be OR-ed together. Any event that is set in the eEvents will be disabled , the other events won't be touched. Precondition: None. Parameters: eEvents - Events with the significance described in the eEthEvents definition. Returns: None. Example: EthEventsEnableClr(ETH_EV_ALL); Remarks: None. *****************************************************************************/ void EthEventsEnableClr ( eEthEvents eEvents ); /******************************************************************************* Function: void EthEventsEnableWrite ( eEthEvents eEvents ) Summary: Enables the events that will generate interrupts for the Ethernet controller. Description: This function enables the events that will generate interrupts for the Ethernet controller. The enabled events are forced to the eEvents value. Precondition: None. Parameters: eEvents - Events with the significance described in the eEthEvents definition. Returns: None. Example: EthEventsEnableWrite( ETH_EV_RXOVFLOW | ETH_EV_RXBUFNA | ETH_EV_TXABORT | ETH_EV_RXACT | ETH_EV_PKTPEND | ETH_EV_RXBUSERR | ETH_EV_TXBUSERR ); Remarks: None. *****************************************************************************/ void EthEventsEnableWrite ( eEthEvents eEvents ); /******************************************************************************* Function: eEthEvents EthEventsEnableGet ( void ) Summary: Returns the enabled events for the Ethernet controller. Description: This function returns the enabled events for the Ethernet controller. Precondition: None. Parameters: None. Returns: eEvents - events with the significance described in the eEthEvents definition. Example: ethEnabledEvents = EthEventsEnableGet(); Remarks: None. *****************************************************************************/ eEthEvents EthEventsEnableGet ( void ); /******************************************************************************* Function: void EthEventsClr ( eEthEvents eEvents ) Summary: Clears the selected events for the Ethernet controller. Description: The function clears the selected events for the Ethernet controller. Multiple events can be OR-ed together. Any event that is set in the eEvents will be cleared, the other events won't be touched. Precondition: None. Parameters: eEvents - Events with the significance described in the eEthEvents definition. Returns: None. Example: EthEventsClr(ETH_EV_TXDONE); Remarks: The ETH_EV_FWMARK cannot be cleared directly. It is cleared indirectly by EthRxAcknowledgePacket/EthRxAcknowledgeBuffer. The ETH_EV_EWMARK cannot be cleared directly. It is cleared by hardware when receiving a new packet. The ETH_EV_PKTPEND cannot be cleared directly. It is cleared indirectly by EthRxAcknowledgePacket/EthRxAcknowledgeBuffer. *****************************************************************************/ void EthEventsClr ( eEthEvents eEvents ); // DOM-IGNORE-BEGIN extern __inline__ void __attribute__((always_inline)) EthEventsClr(eEthEvents eEvents) { ETHIRQCLR=eEvents; } // DOM-IGNORE-END /******************************************************************************* Function: eEthEvents EthEventsGet ( void ) Summary: Returns the active events for the Ethernet controller. Description: This function returns the active events for the Ethernet controller. Precondition: None. Parameters: None. Returns: Events with the significance described in the eEthEvents definition. Example: ethEvents = EthEventsGet(); Remarks: None. *****************************************************************************/ eEthEvents EthEventsGet ( void ); // DOM-IGNORE-BEGIN extern __inline__ eEthEvents __attribute__((always_inline)) EthEventsGet(void) { return (eEthEvents)ETHIRQ; } // DOM-IGNORE-END // Section: Ethernet Statistics Functions /******************************************************************************* Function: int EthStatRxOvflCnt ( void ) Summary: Returns the current number of dropped receive frames. Description: This function returns the current number of dropped receive frames by the Ethernet controller. These are frames accepted by the RX filter but dropped due to internal receive error (RX FIFO overrun). Precondition: None. Parameters: None. Returns: The number of dropped receive frames Example: droppedFrames = EthStatRxOvflCnt(); Remarks: This statistics register is cleared by the read operation. An RX overflow event is signalled by the ETH_EV_RXOVFLOW event (see eEthEvents definition). *****************************************************************************/ int EthStatRxOvflCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatRxOvflCnt() (ETHRXOVFLOW) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatRxOkCnt ( void ) Summary: Returns the current number of successfully received frames. Description: This function returns the current number of successfully received frames by the Ethernet controller. These are frames accepted by the RX filter (some of them may still be dropped because of an RX FIFO overrun). Precondition: None. Parameters: None. Returns: The number of frames received OK Example: numReceived = EthStatRxOkCnt(); Remarks: This statistics register is cleared by the read operation. Frames with FCS or alignment errors will not increment this count. *****************************************************************************/ int EthStatRxOkCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatRxOkCnt() (ETHFRMRXOK) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatRxFcsErrCnt ( void ) Summary: Returns the current number of frames with FCS received errors. Description: The function returns the current number of frames with FCS errors received by the Ethernet controller. These are received frames that have an integral number of bytes. Precondition: None. Parameters: None. Returns: The number of received frames having FCS errors Example: numRxFcsErrors = EthStatRxFcsErrCnt(); Remarks: This statistics register is cleared by the read operation. Frames with alignment error do not increment this count. *****************************************************************************/ int EthStatRxFcsErrCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatRxFcsErrCnt() (ETHFCSERR) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatRxAlgnErrCnt ( void ) Summary: Returns the current number of frames with alignment received errors Description: The function returns the current number of frames with alignment errors received by the Ethernet controller. These are received frames that have FCS error and they do not contain an integral number of bytes (aka dribble-nibble). Precondition: None. Parameters: None. Returns: The number of received frames having alignment errors Example: numAlignErrors = EthStatRxAlgnErrCnt(); Remarks: This statistics register is cleared by the read operation. *****************************************************************************/ int EthStatRxAlgnErrCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatRxAlgnErrCnt() (ETHALGNERR) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatTxOkCnt ( void ) Summary: Returns the current number of frames transmitted successfully Description: The function returns the current number of frames transmitted successfully by the Ethernet controller. Precondition: None. Parameters: None. Returns: The number of frames transmitted OK Example: numFramesTx = EthStatTxOkCnt(); Remarks: This statistics register is cleared by the read operation. *****************************************************************************/ int EthStatTxOkCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatTxOkCnt() (ETHFRMTXOK) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatTxSColCnt ( void ) Summary: Returns the current number of successfully transmitted frames on the second try Description: This function returns the current number of transmitted frames that had a collision but were successfully transmitted by the Ethernet controller on the second try. Precondition: None. Parameters: None. Returns: The number of single collision frames Example: numSingleCollisions = EthStatTxSColCnt(); Remarks: This statistics register is cleared by the read operation. *****************************************************************************/ int EthStatTxSColCnt ( void ); // DOM-IGNORE-BEGIN #define EthStatTxSColCnt() (ETHSCOLFRM) // DOM-IGNORE-END /******************************************************************************* Function: int EthStatTxMColCnt( void ) Summary: Returns the number of current frames transmitted after more than one collision occurred. Description: The function returns the current number of frames successfully transmitted by the Ethernet controller after there was more than one collision. Precondition: None. Parameters: None. Returns: The number of multiple collision frames Example: numMultiCollisions = EthStatTxMColCnt(); Remarks: This statistics register is cleared by the read operation. *****************************************************************************/ int EthStatTxMColCnt( void ); // DOM-IGNORE-BEGIN #define EthStatTxMColCnt() (ETHMCOLFRM) // DOM-IGNORE-END // Section: MIIM Access Functions /******************************************************************************* Function: void EthMIIMConfig ( unsigned int hostClock, unsigned int miimClock ) Summary: Configures and initializes the MIIM interface clock Description: This function initializes and configures the MIIM interface for access of a PHY. Precondition: None. Parameters: hostClock - The value of the host clock, Hz miimClock - The maximum clock frequency that the PHY can use for the MIIM transactions, Hz Returns: None. Example: EthMIIMConfig(MY_HOST_CLOCK_HZ, MY_MIIM_CLOCK_HZ); Remarks: Any previous MIIM operation will be aborted! *****************************************************************************/ void EthMIIMConfig ( unsigned int hostClock, unsigned int miimClock ); /******************************************************************************* Function: void EthMIIMReadStart ( unsigned int rIx, unsigned int phyAdd ) Summary: Initiates a read operation from a PHY register Description: This function initiates a read operation from a PHY register using the MIIM interface. It returns immediately without waiting for the transactions to be performed. Precondition: EthMIIMConfig() called rIx a valid PHY register, 0-31 phyAdd a valid PHY address, 0-31 Parameters: rIx - PHY register to be accessed phyAdd - PHY address Returns: None. Example: while(EthMIIMBusy()); // wait device not busy EthMIIMReadStart(12, 1); Remarks: It assumes that no scan operation is in progress! Before initiating the read operation it waits for the MIIM interface not busy. Call EthMIIMBusy() before if no polling needed! *****************************************************************************/ void EthMIIMReadStart ( unsigned int rIx, unsigned int phyAdd ); /******************************************************************************* Function: unsigned short EthMIIMReadResult ( void ) Summary: Returns the result of a previously started read operation Description: This function returns the result of a previously started read operation (using EthMIIMReadStart()). Precondition: EthMIIMConfig() called EthMIIMReadStart() called Parameters: None. Returns: PHY register value Example: while(EthMIIMBusy()); // wait read operation complete regValue = EthMIIMReadResult(); Remarks: It assumes that no scan operation is in progress! It waits for the read operation to be complete. Call EthMIIMBusy() before if no polling needed! *****************************************************************************/ unsigned short EthMIIMReadResult ( void ); /******************************************************************************* Function: void EthMIIMWriteStart ( unsigned int rIx, unsigned int phyAdd, unsigned short wData ) Summary: Performs a write operation to a PHY register Description: This function performs a write operation to a PHY register using the MIIM interface. It doesn't wait for the write to take effect. Precondition: EthMIIMConfig() called rIx a valid PHY register, 0-31 phyAdd a valid PHY address, 0-31 Parameters: rIx - PHY register to be accessed phyAdd - PHY address wData - Data to be written Returns: None. Example: EthMIIMWriteStart(12, 1, 0x001F); Remarks: It assumes that no scan operation is in progress! Before initiating the write operation it waits for the MIIM interface not busy. Call EthMIIMBusy() before if no polling needed! After write started call EthMIIMBusy() to check if the operation has been completed. *****************************************************************************/ void EthMIIMWriteStart ( unsigned int rIx, unsigned int phyAdd, unsigned short wData ); /******************************************************************************* Function: void EthMIIMScanStart ( unsigned int rIx, unsigned int phyAdd ) Summary: Initiates a scan operation to a PHY register Description: This function initiates a scan operation to a PHY register using the MIIM interface. Precondition: EthMIIMConfig() called rIx a valid PHY register, 0-31 phyAdd a valid PHY address, 0-31 Parameters: rIx - PHY register to be accessed phyAdd - PHY address Returns: None. Example: while(EthMIIMBusy()); // wait device not busy EthMIIMScanStart(12, 1); Remarks: It assumes that no scan operation is in progress! Before initiating the scan operation it waits for the MIIM interface not busy. Call EthMIIMBusy() before if no polling needed! *****************************************************************************/ void EthMIIMScanStart ( unsigned int rIx, unsigned int phyAdd ); /******************************************************************************* Function: unsigned short EthMIIMScanResult ( void ) Summary: Reads the result of a previously initiated scan operation Description: This function reads the result of a previously initiated scan operation from a PHY register using the MIIM interface. Precondition: EthMIIMConfig() called EthMIIMScanStart() called Parameters: None. Returns: Result of previous scan operation Example: if ( EthMIIMScanValid() ) { value = EthMIIMScanResult(); } Remarks: It assumes that a scan operation is in progress! Before returning it waits for the scan result to be valid. Call EthMIIMScanValid() before if no polling needed! *****************************************************************************/ unsigned short EthMIIMScanResult ( void ); /******************************************************************************* Function: void EthMIIMScanStop ( void ) Summary: Stops a previously initiated scan operation Description: This function stops a previously initiated scan operation from a PHY register using the MIIM interface. It doesn't wait for the scan operation to finish. Precondition: EthMIIMConfig() called EthMIIMScanStart() called Parameters: None. Returns: None. Example: EthMIIMScanStop(); while(EthMIIMBusy()); // wait scan stop is in effect Remarks: It assumes that a scan operation is in progress! After call use EthMIIMBusy() to check if the scan has been effectively stopped. *****************************************************************************/ void EthMIIMScanStop ( void ); // DOM-IGNORE-BEGIN extern __inline__ void __attribute__((always_inline)) EthMIIMScanStop(void) { EMACxMCMD=0; // cancel scan } // DOM-IGNORE-END /******************************************************************************* Function: int EthMIIMScanValid ( void ) Summary: Returns the current state of the MIIM scan operation Description: This function returns the current validity state of the MIIM scan operation. Precondition: EthMIIMConfig() called EthMIIMScanStart() called Parameters: None. Returns: TRUE - If the result of a MIIM scan result is valid FALSE - Otherwise Example: if ( !EthMIIMScanValid()) ) { // Handle invalid scan } Remarks: None. *****************************************************************************/ int EthMIIMScanValid ( void ); // DOM-IGNORE-BEGIN extern __inline__ int __attribute__((always_inline)) EthMIIMScanValid(void) { return EMACxMINDbits.NOTVALID==0; } // DOM-IGNORE-END /******************************************************************************* Function: int EthMIIMBusy ( void ) Summary: Returns the current busy state of the MIIM interface Description: This function returns the current busy state of the MIIM interface. Precondition: EthMIIMConfig() called Parameters: None. Returns: TRUE - If the MIIM is busy with some transaction FALSE - Otherwise Example: do { ; // Nothing } while ( EthMIIMBusy() ); Remarks: Use EthMIIMBusy() to check: - if a read/write/scan operation can be started - if a read/write operation has been completed - if a scan operation has been stopped *****************************************************************************/ int EthMIIMBusy ( void ); // DOM-IGNORE-BEGIN extern __inline__ int __attribute__((always_inline)) EthMIIMBusy(void) { return EMACxMINDbits.MIIMBUSY!=0; } // DOM-IGNORE-END // Section: Ethernet Controller Low Level Access Functions // ***************************************************************************** /* Ethernet Configuration Flags Summary: Defines the Ethernet configuration flags Description: This enumeration defines the Ethernet configuration flags. */ typedef enum { // Configure manual flow control ETH_CONFIG_MANFC /*DOM-IGNORE-BEGIN*/ = _ETHCON1_MANFC_MASK /*DOM-IGNORE-END*/, // Configure auto flow control ETH_CONFIG_AUTOFC /*DOM-IGNORE-BEGIN*/ = _ETHCON1_AUTOFC_MASK /*DOM-IGNORE-END*/, // RX enabled ETH_CONFIG_RXEN /*DOM-IGNORE-BEGIN*/ = _ETHCON1_RXEN_MASK /*DOM-IGNORE-END*/, // Activate the TX logic and send packets ETH_CONFIG_TXRTS /*DOM-IGNORE-BEGIN*/ = _ETHCON1_TXRTS_MASK /*DOM-IGNORE-END*/, // Stop in idle ETH_CONFIG_SIDL /*DOM-IGNORE-BEGIN*/ = _ETHCON1_SIDL_MASK /*DOM-IGNORE-END*/, // Turn on/off the Ethernet controller ETH_CONFIG_ON /*DOM-IGNORE-BEGIN*/ = _ETHCON1_ON_MASK /*DOM-IGNORE-END*/ } eEthConfigFlags; /******************************************************************************* Function: void EthEnable ( int enable ) Summary: Gives access to low level Ethernet controller configuration. Description: The function gives access to low level Ethernet controller configuration. It can turn on/off the controller. Precondition: None. Parameters: enable - Boolean to enable/disable the Ethernet Controller. Returns: None. Example: EthEnable(FALSE); Remarks: The Ethernet controller should be disabled before being configured. *****************************************************************************/ void EthEnable ( int enable ); /******************************************************************************* Function: void EthConfig ( eEthConfigFlags cFlags ) Summary: Configures the Ethernet Controller. Description: The function gives access to low level Ethernet controller configuration. It configures the Ethernet Controller. Precondition: The Ethernet controller must be disabled. Parameters: cFlags - Configuration flags Returns: None. Example: EthEnable(FALSE); EthConfig(ETH_CONFIG_MANFC|ETH_CONFIG_RXEN|ETH_CONFIG_SIDL); EthEnable(TRUE); Remarks: The Ethernet controller should be configured when disabled. *****************************************************************************/ void EthConfig ( eEthConfigFlags cFlags ); /******************************************************************************* Function: void EthConfigSetFlags ( eEthConfigFlags cFlags ) Summary: Sets Ethernet controller configuration flags. Description: The function gives access to low level Ethernet controller configuration. Any flag set in the cFlags will be set, the other flags won't be touched. Precondition: The Ethernet controller must be disabled. Parameters: cFlags - Configuration flags to be set Returns: None. Example: EthEnable(FALSE); EthConfigSetFlags(ETH_CONFIG_MANFC|ETH_CONFIG_RXEN|ETH_CONFIG_SIDL); EthEnable(TRUE); Remarks: The Ethernet controller should be configured when disabled. *****************************************************************************/ void EthConfigSetFlags ( eEthConfigFlags cFlags ); /******************************************************************************* Function: void EthConfigClrFlags ( eEthConfigFlags cFlags ) Summary: Clears Ethernet controller configuration flags. Description: The function gives access to low level Ethernet controller configuration. Any flag set in the cFlags will be cleared, the other flags won't be touched. Precondition: The Ethernet controller must be disabled. Parameters: cFlags - Configuration flags to be cleared Returns: None. Example: EthEnable(FALSE); EthConfigClrFlags(ETH_CONFIG_MANFC|ETH_CONFIG_RXEN|ETH_CONFIG_SIDL); EthEnable(TRUE); Remarks: The Ethernet controller should be configured when disabled. *****************************************************************************/ void EthConfigClrFlags ( eEthConfigFlags cFlags ); /******************************************************************************* Function: void EthConfigTxStAddress ( void *address ) Summary: Sets the address of the TX descriptors. Description: The function gives access to low level Ethernet controller configuration. It sets the address of the TX descriptors in memory. Precondition: There must not be a transmit or DMA engine operation in progress. Parameters: address - Starting physical address of the first TX descriptor Returns: None. Example: EthConfigTxStAddress(VirtToPhys(myTxDcpt)); Remarks: The address must be 4-byte aligned. The address must be a physical address. The address must not be written while any transmit or DMA engine operations are in progress. *****************************************************************************/ void EthConfigTxStAddress ( void *address ); /******************************************************************************* Function: void EthConfigRxStAddress ( void *address ) Summary: Sets the address of the RX descriptors in memory. Description: The function gives access to low level Ethernet controller configuration. It sets the address of the RX descriptors in memory. Precondition: There must not be a receive or DMA engine operation in progress. Parameters: address - Starting physical address of the first RX descriptor Returns: None. Example: EthConfigRxStAddress(VirtToPhys(myRxDcpt)); Remarks: The address must be 4-byte aligned. The address must be a physical address. The address must not be written while any receive or DMA engine operations are in progress. *****************************************************************************/ void EthConfigRxStAddress ( void *address ); /******************************************************************************* Function: void EthAckRxDcpt ( void ) Summary: Acknowledges a RX descriptor. Description: The function gives access to low level Ethernet controller functionality. It acknowledges a receiver descriptor. When called, the number of un-acknowledged RX descriptors(BUFCNT=EthDescriptorsGetRxUnack()) will be decremented by one. Precondition: The RX packet associated with the corresponding descriptor must have already been processed and the RX descriptor should be available for the hardware DMA RX engine re-use. Parameters: None. Returns: None. Example: EthAckRxDcpt(); Remarks: The function should be called after a RX packet is processed and the RX descriptor is available for the hardware re-use. BUFCNT is also decremented by a call to EthRxAcknowledgePacket/EthRxAcknowledgeBuffer. BUFCNT value also directs the auto flow control behavior. *****************************************************************************/ void EthAckRxDcpt ( void ); // DOM-IGNORE-BEGIN extern __inline__ void __attribute__((always_inline)) EthAckRxDcpt(void) { ETHCON1SET=_ETHCON1_BUFCDEC_MASK; } // DOM-IGNORE-END // Section: Ethernet MAC Low Level Access Functions // ***************************************************************************** /* Ethernet MAC Configuration 1 Flags Summary: Ethernet MAC configuration flags (set 1) Description: This enumeration defines set 1 of the Ethernet MAC configuration flags. Remarks: These flags can be OR-ed together to create configuration mask values. */ typedef enum { // Enable RX ETH_MAC_CONFIG1_RXEN /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RXENABLE_MASK /*DOM-IGNORE-END*/, // Pass all RX frames (normal and control) ETH_MAC_CONFIG1_PASS_ALL /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_PASSALL_MASK /*DOM-IGNORE-END*/, // Enable acting on RX-ed PAUSE control frames ETH_MAC_CONFIG1_RX_PAUSE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RXPAUSE_MASK /*DOM-IGNORE-END*/, // Enable TX of PAUSE control frames ETH_MAC_CONFIG1_TX_PAUSE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_TXPAUSE_MASK /*DOM-IGNORE-END*/, // Enable the loopback mode ETH_MAC_CONFIG1_LOOPBACK /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_LOOPBACK_MASK /*DOM-IGNORE-END*/, // Put the TX logic in reset ETH_MAC_CONFIG1_RESET_TFUN /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RESETTFUN_MASK /*DOM-IGNORE-END*/, // Put the MAC Control SUblayer/TX domain logic in reset ETH_MAC_CONFIG1_RESET_TMCS /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RESETTMCS_MASK /*DOM-IGNORE-END*/, // Put the RX logic in reset ETH_MAC_CONFIG1_RESET_RFUN /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RESETRFUN_MASK /*DOM-IGNORE-END*/, // Put the MAC Control SUblayer/RX domain logic in reset ETH_MAC_CONFIG1_RESET_RMCS /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_RESETRMCS_MASK /*DOM-IGNORE-END*/, // Reset the random generator within the TX function ETH_MAC_CONFIG1_RESET_SIM /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_SIMRESET_MASK /*DOM-IGNORE-END*/, // Put the MAC in reset ETH_MAC_CONFIG1_RESET_MAC /*DOM-IGNORE-BEGIN*/ = _EMACxCFG1_SOFTRESET_MASK /*DOM-IGNORE-END*/ } eEthMACConfig1Flags; // ***************************************************************************** /* Ethernet MAC Configuration 2 Flags Summary: Ethernet MAC configuration flags (set 2) Description: This enumeration defines set 2 of the Ethernet MAC configuration flags. Remarks: These flags can be OR-ed together to create configuration mask values. If disabled the MAC will abort when the excessive deferral limit is reached and provide feedback to the host system. */ typedef enum { // Enable full duplex functionality ETH_MAC_CONFIG2_FDUPLEX /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_FULLDPLX_MASK /*DOM-IGNORE-END*/, // Enable length frame check ETH_MAC_CONFIG2_LEN_CHECK /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_LENGTHCK_MASK /*DOM-IGNORE-END*/, // Enable huge frames RX/TX ETH_MAC_CONFIG2_HUGE_FRAME /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_HUGEFRM_MASK /*DOM-IGNORE-END*/, // Enable 4 bytes of proprietary header (ignored by the CRC) ETH_MAC_CONFIG2_DELAY_CRC /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_DELAYCRC_MASK /*DOM-IGNORE-END*/, // Enable CRC append to each TX frame ETH_MAC_CONFIG2_CRC_ENABLE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_CRCENABLE_MASK /*DOM-IGNORE-END*/, // PAD/CRC enable used together with ETH_MAC_CONFIG2_VLAN_PAD and // ETH_MAC_CONFIG2_AUTO_PAD ETH_MAC_CONFIG2_PAD_ENABLE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_PADENABLE_MASK /*DOM-IGNORE-END*/, // Enable padding of al frames to 64 bytes and append valid CRC ETH_MAC_CONFIG2_VLAN_PAD /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_VLANPAD_MASK /*DOM-IGNORE-END*/, // Enable automatic detection by the MAC of the type of frame and pad // accordingly ETH_MAC_CONFIG2_AUTO_PAD /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_AUTOPAD_MASK /*DOM-IGNORE-END*/, // Enable preamble verification and discard packets with preamble errors ETH_MAC_CONFIG2_PURE_PRE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_PUREPRE_MASK /*DOM-IGNORE-END*/, // Allow only packets having preamble fields less than 12 bytes in length ETH_MAC_CONFIG2_LONG_PRE /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_LONGPRE_MASK /*DOM-IGNORE-END*/, // Do not use Binary Exponential Backoff algorithm following a collision, // transmit immediately ETH_MAC_CONFIG2_NO_BACKOFF /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_NOBKOFF_MASK /*DOM-IGNORE-END*/, // After incidentally causing a collision during backpressure the MAC will // immediately retransmit without backoff ETH_MAC_CONFIG2_BP_NO_BACKOFF /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_BPNOBKOFF_MASK /*DOM-IGNORE-END*/, // If enabled the MAC will defer to carrier indefinitely as per the standard. ETH_MAC_CONFIG2_EXCESS_DEFER /*DOM-IGNORE-BEGIN*/ = _EMACxCFG2_EXCESSDFR_MASK /*DOM-IGNORE-END*/, } eEthMACConfig2Flags; // ***************************************************************************** /* Ethernet MAC Configuration Supplemental Flags Summary: Ethernet MAC configuration supplemental flags Description: This enumeration defines the supplemental Ethernet MAC configuration flags. Remarks: These flags can be OR-ed together to create configuration mask values. */ typedef enum { // Reset RMII module ETH_MAC_CONFIG_SUPP_RMII_RESET /*DOM-IGNORE-BEGIN*/ = _EMACxSUPP_RESETRMII_MASK /*DOM-IGNORE-END*/, // 100 Mbps RMII operation ETH_MAC_CONFIG_SUPP_RMII_SPEED /*DOM-IGNORE-BEGIN*/ = _EMACxSUPP_SPEEDRMII_MASK /*DOM-IGNORE-END*/ } eEthMACConfigSuppFlags; /******************************************************************************* Function: void EthMACConfig ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ) Summary: Configures the MAC Description: This function gives access to low level Ethernet MAC configuration. It configures the MAC. Precondition: None. Parameters: c1Flags - Configuration flags from set 1 c2Flags - Configuration flags from set 2 sFlags - Suplemental configuration flags Returns: None. Example: EthMACConfig( ETH_MAC_CONFIG1_RXEN|ETH_MAC_CONFIG1_RX_PAUSE|ETH_MAC_CONFIG1_TX_PAUSE, ETH_MAC_CONFIG2_FDUPLEX|ETH_MAC_CONFIG2_HUGE_FRAME, ETH_MAC_CONFIG_SUPP_RMII_SPEED ); Remarks: When connected to an external PHY the MAC and PHY configurations have to be consistent. *****************************************************************************/ void EthMACConfig ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ); /******************************************************************************* Function: void EthMACConfigSetFlags ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ); Summary: Sets Ethernet MAC configuration flags Description: The function gives access to low level Ethernet MAC configuration. Any flag set in the c1Flags, c2Flags, sFlags will be set, the other flags won't be touched. Precondition: None. Parameters: c1Flags - Configuration flags from set 1 to be set c2Flags - Configuration flags from set 2 to be set sFlags - Suplemental configuration flags to be set Returns: None. Example: EthMACConfigSetFlags( ETH_MAC_CONFIG1_RXEN|ETH_MAC_CONFIG1_RX_PAUSE|ETH_MAC_CONFIG1_TX_PAUSE, ETH_MAC_CONFIG2_FDUPLEX|ETH_MAC_CONFIG2_HUGE_FRAME, ETH_MAC_CONFIG_SUPP_RMII_RESET); Remarks: When connected to an external PHY the MAC and PHY configurations have to be consistent. *****************************************************************************/ void EthMACConfigSetFlags ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ); /******************************************************************************* Function: void EthMACConfigClrFlags ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ); Summary: Clears Ethernet MAC configuration flags Description: The function gives access to low level Ethernet MAC configuration. Any flag set in the c1Flags, c2Flags, sFlags will be cleared, the other flags won't be touched. Precondition: None. Parameters: c1Flags - Configuration flags from set 1 to be cleared c2Flags - Configuration flags from set 2 to be cleared sFlags - Suplemental configuration flags to be cleared Returns: None. Example: EthMACConfigClrFlags( ETH_MAC_CONFIG1_RXEN|ETH_MAC_CONFIG1_RX_PAUSE|ETH_MAC_CONFIG1_TX_PAUSE, ETH_MAC_CONFIG2_FDUPLEX|ETH_MAC_CONFIG2_HUGE_FRAME, ETH_MAC_CONFIG_SUPP_RMII_RESET ); Remarks: When connected to an external PHY the MAC and PHY configurations have to be consistent. *****************************************************************************/ void EthMACConfigClrFlags ( eEthMACConfig1Flags c1Flags, eEthMACConfig2Flags c2Flags, eEthMACConfigSuppFlags sFlags ); /******************************************************************************* Function: void EthMACConfigB2BIpGap ( unsigned int ipGap ) Summary: Sets the back to back inter packet gap Description: The function sets the back to back inter packet gap value (the nibble time offset of the minimum possible period between the end of any transmitted packet to the beginning of the next). Precondition: 0 < ipGap < 128 Parameters: ipGap - The back to back inter packet gap Returns: None. Example: EthMACConfigB2BIpGap(0x15); Remarks: In full duplex the recommended value is 0x15. In half duplex the recommended value is 0x12. *****************************************************************************/ void EthMACConfigB2BIpGap ( unsigned int ipGap ); /******************************************************************************* Function: void EthMACConfigNB2BIpGap ( unsigned int ipgr1, unsigned int ipgr2 ) Summary: Sets the non-back-to-back inter-packet gap value. Description: The function sets the non back to back inter packet gap value part 1 and 2. The ipgr1 represents the optional carrierSense window referenced in IEEE 802.3/4.2.3.2.1 Carrier Deference. If carrier is detected during the timing of IPGR1, the MAC defers to carrier. If, however, carrier becomes active after IPGR1, the MAC continues timing IPGR2 and transmits, knowingly causing a collision, thus ensuring fair access to medium. The ipgr2 represents the non back to back inter packet gap. Precondition: 0 < carrDefer < 128 0 < nB2BIpGap < 128 Parameters: carrDefer - The carrier deference nB2BIpGap - Non back to back inter packet gap Returns: None. Example: EthMACConfigNB2BIpGap(0xc, 0x12); Remarks: The ipgr1 recommended value is 0xc. Its range of values is 0x0 to ipgr2. The ipgr2 recommended value is 0x12. *****************************************************************************/ void EthMACConfigNB2BIpGap ( unsigned int ipgr1, unsigned int ipgr2 ); /******************************************************************************* Function: void EthMACConfigCollWinRetry ( unsigned int collWin, unsigned int retMax ) Summary: Sets the collision window and the retransmission maximum. Description: The function sets the collision window and the retransmission maximum. The collision window is a programmable field representing the slot time or collision window during which collisions occur in properly configured networks. Since the collision window starts at the beginning of transmission, the preamble and SFD is included. The retransmission maximum is a programmable field specifying the number of retransmission attempts following a collision before aborting the packet due to excessive collisions. Precondition: 0 < collWin < 64 0 < retMax < 16 Parameters: collWin - The collision window retMax - Retransmission maximum Returns: None. Example: EthMACConfigCollWinRetry(0x37, 0xf); Remarks: The collWin recommended value is 0x37 which corresponds to the count of frame bytes at the end of the window. The retMax recommended value is 0xf. *****************************************************************************/ void EthMACConfigCollWinRetry ( unsigned int collWin, unsigned int retMax ); /******************************************************************** * Include legacy Ethernet functions * New projects should not use them! * The functions in the eth.h should be used instead. ********************************************************************/ #ifndef _PLIB_DISABLE_LEGACY #include #endif #endif // _ETH #endif // _ETH_H_