SAMV71 Xplained Ultra Software Package 1.5

gmacd.h

Go to the documentation of this file.
00001 /* ---------------------------------------------------------------------------- */
00002 /*                  Atmel Microcontroller Software Support                      */
00003 /*                       SAM Software Package License                           */
00004 /* ---------------------------------------------------------------------------- */
00005 /* Copyright (c) 2015, Atmel Corporation                                        */
00006 /*                                                                              */
00007 /* All rights reserved.                                                         */
00008 /*                                                                              */
00009 /* Redistribution and use in source and binary forms, with or without           */
00010 /* modification, are permitted provided that the following condition is met:    */
00011 /*                                                                              */
00012 /* - Redistributions of source code must retain the above copyright notice,     */
00013 /* this list of conditions and the disclaimer below.                            */
00014 /*                                                                              */
00015 /* Atmel's name may not be used to endorse or promote products derived from     */
00016 /* this software without specific prior written permission.                     */
00017 /*                                                                              */
00018 /* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
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     SYNC_MSG_TYPE = 0,
00105     DELAY_REQ_MSG_TYPE = 1,
00106     PDELAY_REQ_TYPE = 2,
00107     PDELAY_RESP_TYPE = 3,
00108     FOLLOW_UP_MSG_TYPE = 8,
00109     DELAY_RESP_MSG_TYPE = 9
00110 } ptpMsgType;
00111 
00112 
00113 
00114 /** RX callback */
00115 typedef void (*fGmacdTransferCallback)(uint32_t status);
00116 /** Wakeup callback */
00117 typedef void (*fGmacdWakeupCallback)(void);
00118 /** Tx PTP message callback */
00119 typedef void (*fGmacdTxPtpEvtCallBack) (ptpMsgType msg, uint32_t sec, \
00120                                         uint32_t nanosec, uint16_t seqId);
00121 
00122 /**
00123  * GMAC scatter-gather entry.
00124  */
00125 typedef struct _GmacSG {
00126     uint32_t size;
00127     void *pBuffer;
00128 } sGmacSG;
00129 
00130 /**
00131  * GMAC scatter-gather list.
00132  */
00133 typedef struct _GmacSGList {
00134     uint32_t len;
00135     sGmacSG  *sg;
00136 } sGmacSGList;
00137 
00138 /**
00139  * GMAC Queue driver.
00140  */
00141 typedef struct _GmacQueueDriver {
00142     uint8_t *pTxBuffer;
00143     /** Pointer to allocated RX buffer */
00144     uint8_t *pRxBuffer;
00145 
00146     /** Pointer to Rx TDs (must be 8-byte aligned) */
00147     sGmacRxDescriptor *pRxD;
00148     /** Pointer to Tx TDs (must be 8-byte aligned) */
00149     sGmacTxDescriptor *pTxD;
00150 
00151     /** Optional callback to be invoked once a frame has been received */
00152     fGmacdTransferCallback fRxCb;
00153     /** Optional callback to be invoked once several TD have been released */
00154     fGmacdWakeupCallback fWakupCb;
00155     /** Optional callback list to be invoked once TD has been processed */
00156     fGmacdTransferCallback *fTxCbList;
00157 
00158     /** Optional callback to be invoked on transmit of PTP Event messages */
00159     fGmacdTxPtpEvtCallBack fTxPtpEvtCb;
00160 
00161     /** RX TD list size */
00162     uint16_t wRxListSize;
00163     /** RX index for current processing TD */
00164     uint16_t wRxI;
00165 
00166     /** TX TD list size */
00167     uint16_t wTxListSize;
00168     /** Circular buffer head pointer by upper layer (buffer to be sent) */
00169     uint16_t wTxHead;
00170     /** Circular buffer tail pointer incremented by handlers (buffer sent) */
00171     uint16_t wTxTail;
00172 
00173     /** Number of free TD before wakeup callback is invoked */
00174     uint8_t  bWakeupThreshold;
00175 
00176     /** RX buffer size */
00177     uint16_t wTxBufferSize;
00178     uint16_t wRxBufferSize;
00179 
00180 } sGmacQd;
00181 
00182 /**
00183  * GMAC driver struct.
00184  */
00185 typedef struct _GmacDriver {
00186 
00187     /** Pointer to HW register base */
00188     Gmac        *pHw;
00189     /** HW ID */
00190     uint8_t bId;
00191     /** Base Queue list params **/
00192     sGmacQd     queueList[NUM_GMAC_QUEUES];
00193 } sGmacd;
00194 
00195 /**
00196  * GMAC driver init struct.
00197  */
00198 typedef struct _GmacInit {
00199     uint32_t bIsGem: 1;
00200     uint32_t reserved: 31;
00201 
00202     uint8_t bDmaBurstLength;
00203 
00204     /** RX descriptor and data buffers */
00205     uint8_t *pRxBuffer;
00206     /** RX data buffers: should be wRxBufferSize * wRxSize byte long in a DMA
00207     capable memory region */
00208     sGmacRxDescriptor *pRxD;
00209     /** RX buffer descriptors: should have wRxSize entries in a DMA
00210     capable memory region */
00211     uint16_t wRxBufferSize;     /** size of a single RX data buffer */
00212     uint16_t wRxSize;           /** number of RX descriptor and data buffers */
00213 
00214     /** TX descriptor and data buffers */
00215     /** TX data buffers: should be wTxBufferSize * wTxSize byte long
00216         in a DMA capable memory region */
00217     uint8_t *pTxBuffer;
00218     /** TX buffer descriptors: should have wTxSize entries
00219         in a DMA capable non-cached memory region */
00220     sGmacTxDescriptor *pTxD;
00221     /** size of a single TX data buffer */
00222     uint16_t wTxBufferSize;
00223     /** number of TX descriptor and data buffers */
00224     uint16_t wTxSize;
00225 
00226     fGmacdTransferCallback *pTxCb;      /** should have wTxSize entries */
00227 } sGmacInit;
00228 /** @}*/
00229 
00230 /** \addtogroup gmacd_functions
00231     @{*/
00232 
00233 /*---------------------------------------------------------------------------
00234  *         GMAC Exported functions
00235  *---------------------------------------------------------------------------*/
00236 
00237 extern void GMACD_Handler(sGmacd *pGmacd , gmacQueList_t queIdx);
00238 
00239 extern void GMACD_Init(sGmacd *pGmacd,
00240                        Gmac *pHw,
00241                        uint8_t bID,
00242                        uint8_t enableCAF,
00243                        uint8_t enableNBC);
00244 
00245 extern uint8_t GMACD_InitTransfer(sGmacd *pGmacd,
00246                                   const sGmacInit *pInit, gmacQueList_t queIdx);
00247 
00248 extern void GMACD_Reset(sGmacd *pGmacd);
00249 
00250 extern uint8_t GMACD_SendSG(sGmacd *pGmacd,
00251                             const sGmacSGList *sgl,
00252                             fGmacdTransferCallback fTxCb,
00253                             gmacQueList_t queIdx);
00254 
00255 extern uint8_t GMACD_Send(sGmacd *pGmacd,
00256                           void *pBuffer,
00257                           uint32_t size,
00258                           fGmacdTransferCallback fTxCb,
00259                           gmacQueList_t queIdx);
00260 
00261 extern  uint32_t GMACD_TxLoad(sGmacd *pGmacd, gmacQueList_t queIdx);
00262 
00263 extern  uint8_t GMACD_Poll(sGmacd *pGmacd,
00264                            uint8_t *pFrame,
00265                            uint32_t frameSize,
00266                            uint32_t *pRcvSize,
00267                            gmacQueList_t queIdx);
00268 
00269 extern void GMACD_SetRxCallback(sGmacd *pGmacd, fGmacdTransferCallback
00270                                 fRxCb, gmacQueList_t queIdx);
00271 
00272 extern uint8_t GMACD_SetTxWakeupCallback(sGmacd *pGmacd,
00273         fGmacdWakeupCallback fWakeup,
00274         uint8_t bThreshold,
00275         gmacQueList_t queIdx);
00276 
00277 extern void GMACD_TxPtpEvtMsgCBRegister (sGmacd *pGmacd,
00278         fGmacdTxPtpEvtCallBack pTxPtpEvtCb,
00279         gmacQueList_t queIdx);
00280 
00281 /** @}*/
00282 
00283 #endif // #ifndef _GMACD_H_
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines