source: rtems/bsps/arm/atsam/include/libchip/include/gmacd.h @ 2afb22b

Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 9.1 KB
Line 
1/* ---------------------------------------------------------------------------- */
2/*                  Atmel Microcontroller Software Support                      */
3/*                       SAM Software Package License                           */
4/* ---------------------------------------------------------------------------- */
5/* Copyright (c) 2015, Atmel Corporation                                        */
6/*                                                                              */
7/* All rights reserved.                                                         */
8/*                                                                              */
9/* Redistribution and use in source and binary forms, with or without           */
10/* modification, are permitted provided that the following condition is met:    */
11/*                                                                              */
12/* - Redistributions of source code must retain the above copyright notice,     */
13/* this list of conditions and the disclaimer below.                            */
14/*                                                                              */
15/* Atmel's name may not be used to endorse or promote products derived from     */
16/* this software without specific prior written permission.                     */
17/*                                                                              */
18/* DISCLAIMER:  THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR   */
19/* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */
20/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE   */
21/* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,      */
22/* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */
23/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,  */
24/* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    */
25/* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING         */
26/* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */
27/* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                           */
28/* ---------------------------------------------------------------------------- */
29
30/** \file */
31
32/** \addtogroup gmacd_module
33 * @{
34 * Implement GMAC data transfer and PHY management functions.
35 *
36 * \section Usage
37 * -# Implement GMAC interrupt handler, which must invoke GMACD_Handler()
38 *    to handle GMAC interrupt events.
39 * -# Implement sGmacd instance in application.
40 * -# Initialize the instance with GMACD_Init() and GMACD_InitTransfer(),
41 *    so that GMAC data can be transmitted/received.
42 * -# Some management callbacks can be set by GMACD_SetRxCallback()
43 *    and GMACD_SetTxWakeupCallback().
44 * -# Send ethernet packets using GMACD_Send(), GMACD_TxLoad() is used
45 *    to check the free space in TX queue.
46 * -# Check and obtain received ethernet packets via GMACD_Poll().
47 *
48 * \sa \ref gmacb_module, \ref gmac_module
49 *
50 * Related files:\n
51 * \ref gmacd.c\n
52 * \ref gmacd.h.\n
53 *
54 *  \defgroup gmacd_defines GMAC Driver Defines
55 *  \defgroup gmacd_types GMAC Driver Types
56 *  \defgroup gmacd_functions GMAC Driver Functions
57 */
58/**@}*/
59
60#ifndef _GMACD_H_
61#define _GMACD_H_
62
63/*---------------------------------------------------------------------------
64 *         Headers
65 *---------------------------------------------------------------------------*/
66
67#include "chip.h"
68
69
70/*---------------------------------------------------------------------------
71 *         Definitions
72 *---------------------------------------------------------------------------*/
73/** \addtogroup gmacd_defines
74    @{*/
75
76
77/** \addtogroup gmacd_rc GMACD Return Codes
78        @{*/
79#define GMACD_OK                0   /**< Operation OK */
80#define GMACD_TX_BUSY           1   /**< TX in progress */
81#define GMACD_RX_NULL           1   /**< No data received */
82/** Buffer size not enough */
83#define GMACD_SIZE_TOO_SMALL    2
84/** Parameter error, TX packet invalid or RX size too small */
85#define GMACD_PARAM             3
86/** Transfer is not initialized */
87#define GMACD_NOT_INITIALIZED   4
88/**     @}*/
89
90/** @}*/
91
92/* Should be a power of 2.
93   - Buffer Length to store the timestamps of 1588 event messages
94*/
95#define EFRS_BUFFER_LEN (1u)
96
97/*---------------------------------------------------------------------------
98*             Types
99*---------------------------------------------------------------------------*/
100/** \addtogroup gmacd_types
101    @{*/
102
103typedef enum ptpMsgType_t {
104        SYNC_MSG_TYPE = 0,
105        DELAY_REQ_MSG_TYPE = 1,
106        PDELAY_REQ_TYPE = 2,
107        PDELAY_RESP_TYPE = 3,
108        FOLLOW_UP_MSG_TYPE = 8,
109        DELAY_RESP_MSG_TYPE = 9
110} ptpMsgType;
111
112
113
114/** RX callback */
115typedef void (*fGmacdTransferCallback)(uint32_t status);
116/** Wakeup callback */
117typedef void (*fGmacdWakeupCallback)(void);
118/** Tx PTP message callback */
119typedef void (*fGmacdTxPtpEvtCallBack) (ptpMsgType msg, uint32_t sec, \
120                                                                                uint32_t nanosec, uint16_t seqId);
121
122/**
123 * GMAC scatter-gather entry.
124 */
125typedef struct _GmacSG {
126        uint32_t size;
127        void *pBuffer;
128} sGmacSG;
129
130/**
131 * GMAC scatter-gather list.
132 */
133typedef struct _GmacSGList {
134        uint32_t len;
135        sGmacSG  *sg;
136} sGmacSGList;
137
138/**
139 * GMAC Queue driver.
140 */
141typedef struct _GmacQueueDriver {
142        uint8_t *pTxBuffer;
143        /** Pointer to allocated RX buffer */
144        uint8_t *pRxBuffer;
145
146        /** Pointer to Rx TDs (must be 8-byte aligned) */
147        sGmacRxDescriptor *pRxD;
148        /** Pointer to Tx TDs (must be 8-byte aligned) */
149        sGmacTxDescriptor *pTxD;
150
151        /** Optional callback to be invoked once a frame has been received */
152        fGmacdTransferCallback fRxCb;
153        /** Optional callback to be invoked once several TD have been released */
154        fGmacdWakeupCallback fWakupCb;
155        /** Optional callback list to be invoked once TD has been processed */
156        fGmacdTransferCallback *fTxCbList;
157
158        /** Optional callback to be invoked on transmit of PTP Event messages */
159        fGmacdTxPtpEvtCallBack fTxPtpEvtCb;
160
161        /** RX TD list size */
162        uint16_t wRxListSize;
163        /** RX index for current processing TD */
164        uint16_t wRxI;
165
166        /** TX TD list size */
167        uint16_t wTxListSize;
168        /** Circular buffer head pointer by upper layer (buffer to be sent) */
169        uint16_t wTxHead;
170        /** Circular buffer tail pointer incremented by handlers (buffer sent) */
171        uint16_t wTxTail;
172
173        /** Number of free TD before wakeup callback is invoked */
174        uint8_t  bWakeupThreshold;
175
176        /** RX buffer size */
177        uint16_t wTxBufferSize;
178        uint16_t wRxBufferSize;
179
180} sGmacQd;
181
182/**
183 * GMAC driver struct.
184 */
185typedef struct _GmacDriver {
186
187        /** Pointer to HW register base */
188        Gmac        *pHw;
189        /** HW ID */
190        uint8_t bId;
191        /** Base Queue list params **/
192        sGmacQd     queueList[NUM_GMAC_QUEUES];
193} sGmacd;
194
195/**
196 * GMAC driver init struct.
197 */
198typedef struct _GmacInit {
199        uint32_t bIsGem: 1;
200        uint32_t reserved: 31;
201
202        uint8_t bDmaBurstLength;
203
204        /** RX descriptor and data buffers */
205        uint8_t *pRxBuffer;
206        /** RX data buffers: should be wRxBufferSize * wRxSize byte long in a DMA
207        capable memory region */
208        sGmacRxDescriptor *pRxD;
209        /** RX buffer descriptors: should have wRxSize entries in a DMA
210        capable memory region */
211        uint16_t wRxBufferSize;     /** size of a single RX data buffer */
212        uint16_t wRxSize;           /** number of RX descriptor and data buffers */
213
214        /** TX descriptor and data buffers */
215        /** TX data buffers: should be wTxBufferSize * wTxSize byte long
216            in a DMA capable memory region */
217        uint8_t *pTxBuffer;
218        /** TX buffer descriptors: should have wTxSize entries
219            in a DMA capable non-cached memory region */
220        sGmacTxDescriptor *pTxD;
221        /** size of a single TX data buffer */
222        uint16_t wTxBufferSize;
223        /** number of TX descriptor and data buffers */
224        uint16_t wTxSize;
225
226        fGmacdTransferCallback *pTxCb;      /** should have wTxSize entries */
227} sGmacInit;
228/** @}*/
229
230/** \addtogroup gmacd_functions
231    @{*/
232
233/*---------------------------------------------------------------------------
234 *         GMAC Exported functions
235 *---------------------------------------------------------------------------*/
236
237extern void GMACD_Handler(sGmacd *pGmacd , gmacQueList_t queIdx);
238
239extern void GMACD_Init(sGmacd *pGmacd,
240                                           Gmac *pHw,
241                                           uint8_t bID,
242                                           uint8_t enableCAF,
243                                           uint8_t enableNBC);
244
245extern uint8_t GMACD_InitTransfer(sGmacd *pGmacd,
246                                                                  const sGmacInit *pInit, gmacQueList_t queIdx);
247
248extern void GMACD_Reset(sGmacd *pGmacd);
249
250extern uint8_t GMACD_SendSG(sGmacd *pGmacd,
251                                                        const sGmacSGList *sgl,
252                                                        fGmacdTransferCallback fTxCb,
253                                                        gmacQueList_t queIdx);
254
255extern uint8_t GMACD_Send(sGmacd *pGmacd,
256                                                  void *pBuffer,
257                                                  uint32_t size,
258                                                  fGmacdTransferCallback fTxCb,
259                                                  gmacQueList_t queIdx);
260
261extern  uint32_t GMACD_TxLoad(sGmacd *pGmacd, gmacQueList_t queIdx);
262
263extern  uint8_t GMACD_Poll(sGmacd *pGmacd,
264                                                   uint8_t *pFrame,
265                                                   uint32_t frameSize,
266                                                   uint32_t *pRcvSize,
267                                                   gmacQueList_t queIdx);
268
269extern void GMACD_SetRxCallback(sGmacd *pGmacd, fGmacdTransferCallback
270                                                                fRxCb, gmacQueList_t queIdx);
271
272extern uint8_t GMACD_SetTxWakeupCallback(sGmacd *pGmacd,
273                fGmacdWakeupCallback fWakeup,
274                uint8_t bThreshold,
275                gmacQueList_t queIdx);
276
277extern void GMACD_TxPtpEvtMsgCBRegister (sGmacd *pGmacd,
278                fGmacdTxPtpEvtCallBack pTxPtpEvtCb,
279                gmacQueList_t queIdx);
280
281/** @}*/
282
283#endif // #ifndef _GMACD_H_
Note: See TracBrowser for help on using the repository browser.