SAMV71 Xplained Ultra Software Package 1.3

gmacd.h

Go to the documentation of this file.
00001 /* ----------------------------------------------------------------------------
00002  *         SAM Software Package License 
00003  * ----------------------------------------------------------------------------
00004  * Copyright (c) 2012, Atmel Corporation
00005  *
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *
00011  * - Redistributions of source code must retain the above copyright notice,
00012  * this list of conditions and the disclaimer below.
00013  *
00014  * Atmel's name may not be used to endorse or promote products derived from
00015  * this software without specific prior written permission.
00016  *
00017  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00019  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00020  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
00021  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00022  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
00023  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00024  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00025  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00026  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  * ----------------------------------------------------------------------------
00028  */
00029 
00030 /** \file */
00031 
00032 /** \addtogroup gmacd_module
00033  * @{
00034  * Implement GMAC data transfer and PHY management functions.
00035  *
00036  * \section Usage
00037  * -# Implement GMAC interrupt handler, which must invoke GMACD_Handler()
00038  *    to handle GMAC interrupt events.
00039  * -# Implement sGmacd instance in application.
00040  * -# Initialize the instance with GMACD_Init() and GMACD_InitTransfer(),
00041  *    so that GMAC data can be transmitted/received.
00042  * -# Some management callbacks can be set by GMACD_SetRxCallback()
00043  *    and GMACD_SetTxWakeupCallback().
00044  * -# Send ethernet packets using GMACD_Send(), GMACD_TxLoad() is used
00045  *    to check the free space in TX queue.
00046  * -# Check and obtain received ethernet packets via GMACD_Poll().
00047  *
00048  * \sa \ref gmacb_module, \ref gmac_module
00049  *
00050  * Related files:\n
00051  * \ref gmacd.c\n
00052  * \ref gmacd.h.\n
00053  *
00054  *  \defgroup gmacd_defines GMAC Driver Defines
00055  *  \defgroup gmacd_types GMAC Driver Types
00056  *  \defgroup gmacd_functions GMAC Driver Functions
00057  */
00058 /**@}*/
00059 
00060 #ifndef _GMACD_H_
00061 #define _GMACD_H_
00062 
00063 /*---------------------------------------------------------------------------
00064  *         Headers
00065  *---------------------------------------------------------------------------*/
00066 
00067 #include "chip.h"
00068 
00069 
00070 /*---------------------------------------------------------------------------
00071  *         Definitions
00072  *---------------------------------------------------------------------------*/
00073 /** \addtogroup gmacd_defines
00074     @{*/
00075 
00076 
00077 /** \addtogroup gmacd_rc GMACD Return Codes
00078         @{*/
00079 #define GMACD_OK                0   /**< Operation OK */
00080 #define GMACD_TX_BUSY           1   /**< TX in progress */
00081 #define GMACD_RX_NULL           1   /**< No data received */
00082 /** Buffer size not enough */
00083 #define GMACD_SIZE_TOO_SMALL    2
00084 /** Parameter error, TX packet invalid or RX size too small */
00085 #define GMACD_PARAM             3
00086 /** Transfer is not initialized */
00087 #define GMACD_NOT_INITIALIZED   4
00088 /**     @}*/
00089 
00090 /** @}*/
00091 
00092 /* Should be a power of 2. 
00093    - Buffer Length to store the timestamps of 1588 event messages 
00094 */
00095 #define EFRS_BUFFER_LEN (1u)
00096 
00097 /*---------------------------------------------------------------------------
00098 *             Types
00099 *---------------------------------------------------------------------------*/ 
00100 /** \addtogroup gmacd_types
00101     @{*/
00102 
00103 typedef enum ptpMsgType_t  
00104 {
00105     SYNC_MSG_TYPE = 0,
00106     DELAY_REQ_MSG_TYPE = 1,
00107     PDELAY_REQ_TYPE = 2,
00108     PDELAY_RESP_TYPE = 3,
00109     FOLLOW_UP_MSG_TYPE = 8,
00110     DELAY_RESP_MSG_TYPE = 9
00111 }ptpMsgType; 
00112     
00113 
00114 
00115 /** RX callback */
00116 typedef void (*fGmacdTransferCallback)(uint32_t status);
00117 /** Wakeup callback */
00118 typedef void (*fGmacdWakeupCallback)(void);
00119 /** Tx PTP message callback */
00120 typedef void (*fGmacdTxPtpEvtCallBack) (ptpMsgType msg, uint32_t sec, \
00121                     uint32_t nanosec, uint16_t seqId);
00122 
00123 /**
00124  * GMAC scatter-gather entry.
00125  */
00126 typedef struct _GmacSG {
00127     uint32_t size;
00128     void *pBuffer;
00129 } sGmacSG;
00130 
00131 /**
00132  * GMAC scatter-gather list.
00133  */
00134 typedef struct _GmacSGList {
00135     uint32_t len;
00136     sGmacSG  *sg;
00137 } sGmacSGList;
00138 
00139 /**
00140  * GMAC Queue driver.
00141  */
00142 typedef struct _GmacQueueDriver {
00143     uint8_t *pTxBuffer;
00144     /** Pointer to allocated RX buffer */
00145     uint8_t *pRxBuffer;
00146 
00147     /** Pointer to Rx TDs (must be 8-byte aligned) */
00148     sGmacRxDescriptor *pRxD;
00149     /** Pointer to Tx TDs (must be 8-byte aligned) */
00150     sGmacTxDescriptor *pTxD;
00151 
00152     /** Optional callback to be invoked once a frame has been received */
00153     fGmacdTransferCallback fRxCb;
00154     /** Optional callback to be invoked once several TD have been released */
00155     fGmacdWakeupCallback fWakupCb;
00156     /** Optional callback list to be invoked once TD has been processed */
00157     fGmacdTransferCallback *fTxCbList;
00158 
00159     /** Optional callback to be invoked on transmit of PTP Event messages */
00160      fGmacdTxPtpEvtCallBack fTxPtpEvtCb;
00161 
00162       /** RX TD list size */
00163     uint16_t wRxListSize;
00164     /** RX index for current processing TD */
00165     uint16_t wRxI;
00166 
00167     /** TX TD list size */
00168     uint16_t wTxListSize;
00169     /** Circular buffer head pointer by upper layer (buffer to be sent) */
00170     uint16_t wTxHead;
00171     /** Circular buffer tail pointer incremented by handlers (buffer sent) */
00172     uint16_t wTxTail;
00173 
00174     /** Number of free TD before wakeup callback is invoked */
00175     uint8_t  bWakeupThreshold;
00176     
00177    /** RX buffer size */
00178     uint16_t wTxBufferSize;
00179     uint16_t wRxBufferSize;
00180     
00181 } sGmacQd;
00182 
00183 /**
00184  * GMAC driver struct.
00185  */
00186 typedef struct _GmacDriver {
00187 
00188     /** Pointer to HW register base */
00189     Gmac        *pHw;
00190     /** HW ID */
00191     uint8_t bId;
00192     /** Base Queue list params **/
00193     sGmacQd     queueList[NUM_GMAC_QUEUES];    
00194 } sGmacd;
00195 
00196 /**
00197  * GMAC driver init struct.
00198  */
00199 typedef struct _GmacInit {
00200     uint32_t bIsGem:1;
00201     uint32_t reserved:31;
00202 
00203     uint8_t bDmaBurstLength;
00204 
00205     /** RX descriptor and data buffers */
00206     uint8_t *pRxBuffer;        
00207     /** RX data buffers: should be wRxBufferSize * wRxSize byte long in a DMA 
00208     capable memory region */
00209     sGmacRxDescriptor *pRxD;    
00210     /** RX buffer descriptors: should have wRxSize entries in a DMA 
00211     capable memory region */
00212     uint16_t wRxBufferSize;     /** size of a single RX data buffer */
00213     uint16_t wRxSize;           /** number of RX descriptor and data buffers */
00214 
00215     /** TX descriptor and data buffers */
00216     /** TX data buffers: should be wTxBufferSize * wTxSize byte long 
00217         in a DMA capable memory region */
00218     uint8_t *pTxBuffer;
00219     /** TX buffer descriptors: should have wTxSize entries
00220         in a DMA capable non-cached memory region */
00221     sGmacTxDescriptor *pTxD;
00222     /** size of a single TX data buffer */
00223     uint16_t wTxBufferSize;
00224     /** number of TX descriptor and data buffers */
00225     uint16_t wTxSize;
00226 
00227     fGmacdTransferCallback *pTxCb;      /** should have wTxSize entries */
00228 } sGmacInit;
00229 /** @}*/
00230 
00231 /** \addtogroup gmacd_functions
00232     @{*/
00233 
00234 /*---------------------------------------------------------------------------
00235  *         GMAC Exported functions
00236  *---------------------------------------------------------------------------*/
00237 
00238 extern void GMACD_Handler(sGmacd *pGmacd , gmacQueList_t queIdx);
00239 
00240 extern void GMACD_Init(sGmacd *pGmacd,
00241                        Gmac *pHw,
00242                        uint8_t bID, 
00243                        uint8_t enableCAF, 
00244                        uint8_t enableNBC );
00245 
00246 extern uint8_t GMACD_InitTransfer(sGmacd *pGmacd,
00247                                    const sGmacInit *pInit, gmacQueList_t queIdx);
00248 
00249 extern void GMACD_Reset(sGmacd *pGmacd);
00250 
00251 extern uint8_t GMACD_SendSG(sGmacd *pGmacd,
00252                             const sGmacSGList *sgl,
00253                             fGmacdTransferCallback fTxCb, 
00254                             gmacQueList_t queIdx);
00255 
00256 extern uint8_t GMACD_Send(sGmacd *pGmacd,
00257                          void *pBuffer,
00258                          uint32_t size,
00259                          fGmacdTransferCallback fTxCb, 
00260                          gmacQueList_t queIdx );
00261 
00262 extern  uint32_t GMACD_TxLoad(sGmacd *pGmacd, gmacQueList_t queIdx);
00263 
00264 extern  uint8_t GMACD_Poll(sGmacd * pGmacd, 
00265                           uint8_t *pFrame, 
00266                           uint32_t frameSize, 
00267                           uint32_t *pRcvSize, 
00268                           gmacQueList_t queIdx);
00269 
00270 extern void GMACD_SetRxCallback(sGmacd * pGmacd, fGmacdTransferCallback 
00271         fRxCb, gmacQueList_t queIdx);
00272 
00273 extern uint8_t GMACD_SetTxWakeupCallback(sGmacd * pGmacd,
00274                                          fGmacdWakeupCallback fWakeup,
00275                                          uint8_t bThreshold, 
00276                                          gmacQueList_t queIdx);
00277  
00278 extern void GMACD_TxPtpEvtMsgCBRegister (sGmacd * pGmacd, 
00279                                           fGmacdTxPtpEvtCallBack pTxPtpEvtCb, 
00280                                           gmacQueList_t queIdx);
00281 
00282 /** @}*/
00283 
00284 #endif // #ifndef _GMACD_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines