source: rtems/bsps/powerpc/beatnik/include/bsp/if_mve_pub.h @ 2afb22b

5
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: 14.6 KB
Line 
1#ifndef RTEMS_BSDNET_IF_MVE_PUBLIC_SYMBOLS_H
2#define RTEMS_BSDNET_IF_MVE_PUBLIC_SYMBOLS_H
3
4/*
5 * Authorship
6 * ----------
7 * This software ('beatnik' RTEMS BSP for MVME6100 and MVME5500) was
8 *     created by Till Straumann <strauman@slac.stanford.edu>, 2005-2007,
9 *         Stanford Linear Accelerator Center, Stanford University.
10 *
11 * Acknowledgement of sponsorship
12 * ------------------------------
13 * The 'beatnik' BSP was produced by
14 *     the Stanford Linear Accelerator Center, Stanford University,
15 *         under Contract DE-AC03-76SFO0515 with the Department of Energy.
16 *
17 * Government disclaimer of liability
18 * ----------------------------------
19 * Neither the United States nor the United States Department of Energy,
20 * nor any of their employees, makes any warranty, express or implied, or
21 * assumes any legal liability or responsibility for the accuracy,
22 * completeness, or usefulness of any data, apparatus, product, or process
23 * disclosed, or represents that its use would not infringe privately owned
24 * rights.
25 *
26 * Stanford disclaimer of liability
27 * --------------------------------
28 * Stanford University makes no representations or warranties, express or
29 * implied, nor assumes any liability for the use of this software.
30 *
31 * Stanford disclaimer of copyright
32 * --------------------------------
33 * Stanford University, owner of the copyright, hereby disclaims its
34 * copyright and all other rights in this software.  Hence, anyone may
35 * freely use it for any purpose without restriction. 
36 *
37 * Maintenance of notices
38 * ----------------------
39 * In the interest of clarity regarding the origin and status of this
40 * SLAC software, this and all the preceding Stanford University notices
41 * are to remain affixed to any copy or derivative of this software made
42 * or distributed by the recipient and are to be affixed to any copy of
43 * software made or distributed by the recipient that contains a copy or
44 * derivative of this software.
45 *
46 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
47 */ 
48#include <rtems.h>
49#include <rtems/rtems_bsdnet.h>
50#include <bsp/early_enet_link_status.h>
51#include <stdint.h>
52
53#ifdef __cplusplus
54  extern "C" {
55#endif
56
57extern int                               rtems_mve_attach(struct rtems_bsdnet_ifconfig *, int);
58extern rtems_bsdnet_early_link_check_ops rtems_mve_early_link_check_ops;
59
60/* Low-level Driver API.
61 * This provides driver access to applications that want to use e.g., the second
62 * ethernet interface w/o running the BSD TCP/IP stack.
63 */
64
65/* Opaque handle */
66struct mveth_private;
67
68/* Direct assignment of MVE flags to user API relies on irqs and x-irqs not overlapping */
69#define BSP_MVE_IRQ_RX          (1<<2)
70#define BSP_MVE_IRQ_TX          (1<<0)
71#define BSP_MVE_IRQ_LINK        (1<<16)
72
73/* Setup an interface.
74 * Allocates resources for descriptor rings and sets up the driver software structure.
75 *
76 * Arguments:
77 *      unit:
78 *              interface # (1..2). The interface must not be attached to BSD.
79 *
80 *  driver_tid:
81 *              ISR posts RTEMS event # ('unit' - 1) to task with ID 'driver_tid' and disables interrupts
82 *              from this interface.
83 *
84 *      void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred):
85 *              Pointer to user-supplied callback to release a buffer that had been sent
86 *              by BSP_mve_send_buf() earlier. The callback is passed 'cleanup_txbuf_arg'
87 *              and a flag indicating whether the send had been successful.
88 *              The driver no longer accesses 'user_buf' after invoking this callback.
89 *              CONTEXT: This callback is executed either by BSP_mve_swipe_tx() or
90 *              BSP_mve_send_buf(), BSP_mve_init_hw(), BSP_mve_stop_hw() (the latter
91 *              ones calling BSP_mve_swipe_tx()).
92 *      void *cleanup_txbuf_arg:
93 *              Closure argument that is passed on to 'cleanup_txbuf()' callback;
94 *
95 *      void *(*alloc_rxbuf)(int *p_size, unsigned long *p_data_addr),
96 *              Pointer to user-supplied callback to allocate a buffer for subsequent
97 *              insertion into the RX ring by the driver.
98 *              RETURNS: opaque handle to the buffer (which may be a more complex object
99 *                               such as an 'mbuf'). The handle is not used by the driver directly
100 *                               but passed back to the 'consume_rxbuf()' callback.
101 *                               Size of the available data area and pointer to buffer's data area
102 *                               in '*psize' and '*p_data_area', respectively.
103 *                               If no buffer is available, this routine should return NULL in which
104 *                               case the driver drops the last packet and re-uses the last buffer
105 *                               instead of handing it out to 'consume_rxbuf()'.
106 *              CONTEXT: Called when initializing the RX ring (BSP_mve_init_hw()) or when
107 *                               swiping it (BSP_mve_swipe_rx()).
108 *             
109 *
110 *      void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len);
111 *              Pointer to user-supplied callback to pass a received buffer back to
112 *              the user. The driver no longer accesses the buffer after invoking this
113 *              callback (with 'len'>0, see below). 'user_buf' is the buffer handle
114 *              previously generated by 'alloc_rxbuf()'.
115 *              The callback is passed 'cleanup_rxbuf_arg' and a 'len'
116 *              argument giving the number of bytes that were received.
117 *              'len' may be <=0 in which case the 'user_buf' argument is NULL.
118 *              'len' == 0 means that the last 'alloc_rxbuf()' had failed,
119 *              'len' < 0 indicates a receiver error. In both cases, the last packet
120 *              was dropped/missed and the last buffer will be re-used by the driver.
121 *              NOTE: the data are 'prefixed' with two bytes, i.e., the ethernet packet header
122 *                    is stored at offset 2 in the buffer's data area. Also, the FCS (4 bytes)
123 *                    is appended. 'len' accounts for both.
124 *              CONTEXT: Called from BSP_mve_swipe_rx().
125 *      void *cleanup_rxbuf_arg:
126 *              Closure argument that is passed on to 'consume_rxbuf()' callback;
127 *
128 *  rx_ring_size, tx_ring_size:
129 *              How many big to make the RX and TX descriptor rings. Note that the sizes
130 *              may be 0 in which case a reasonable default will be used.
131 *              If either ring size is < 0 then the RX or TX will be disabled.
132 *              Note that it is illegal in this case to use BSP_mve_swipe_rx() or
133 *              BSP_mve_swipe_tx(), respectively.
134 *
135 *  irq_mask:
136 *              Interrupts to enable. OR of flags from above.
137 *
138 */
139struct mveth_private *
140BSP_mve_setup(
141        int              unit,
142        rtems_id driver_tid,
143        void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred), 
144        void *cleanup_txbuf_arg,
145        void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr),
146        void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len),
147        void *consume_rxbuf_arg,
148        int             rx_ring_size,
149        int             tx_ring_size,
150        int             irq_mask
151);
152
153/*
154 * Alternate 'setup' routine allowing the user to install an ISR rather
155 * than a task ID.
156 * All parameters (other than 'isr' / 'isr_arg') and the return value
157 * are identical to the BSP_mve_setup() entry point.
158 */
159struct mveth_private *
160BSP_mve_setup_1(
161        int              unit,
162        void     (*isr)(void *isr_arg),
163        void     *isr_arg,
164        void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred), 
165        void *cleanup_txbuf_arg,
166        void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr),
167        void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len),
168        void *consume_rxbuf_arg,
169        int             rx_ring_size,
170        int             tx_ring_size,
171        int             irq_mask
172);
173
174
175/*
176 * Initialize interface hardware
177 *
178 * 'mp'                 handle obtained by from BSP_mve_setup().
179 * 'promisc'    whether to set promiscuous flag.
180 * 'enaddr'             pointer to six bytes with MAC address. Read
181 *                              from the device if NULL.
182 *
183 * Note:        Multicast filters are cleared by this routine.
184 *              However, in promiscuous mode the mcast filters
185 *              are programmed to accept all multicast frames.
186 */
187void
188BSP_mve_init_hw(struct mveth_private *mp, int promisc, unsigned char *enaddr);
189
190/*
191 * Clear multicast hash filter. No multicast frames are accepted
192 * after executing this routine (unless the hardware was initialized
193 * in 'promiscuous' mode).
194 */
195void
196BSP_mve_mcast_filter_clear(struct mveth_private *mp);
197
198/*
199 * Program multicast filter to accept all multicast frames
200 */
201void
202BSP_mve_mcast_filter_accept_all(struct mveth_private *mp);
203
204/*
205 * Add a MAC address to the multicast filter.
206 * Existing entries are not changed but note that
207 * the filter is imperfect, i.e., multiple MAC addresses
208 * may alias to a single filter entry. Hence software
209 * filtering must still be performed.
210 *
211 * If a higher-level driver implements IP multicasting
212 * then multiple IP addresses may alias to the same MAC
213 * address. This driver maintains a 'reference-count'
214 * which is incremented every time the same MAC-address
215 * is passed to this routine; the address is only removed
216 * from the filter if BSP_mve_mcast_filter_accept_del()
217 * is called the same number of times (or by BSP_mve_mcast_filter_clear).
218 */
219void
220BSP_mve_mcast_filter_accept_add(struct mveth_private *mp, unsigned char *enaddr);
221
222/*
223 * Remove a MAC address from the multicast filter.
224 * This routine decrements the reference count of the given
225 * MAC-address and removes it from the filter once the
226 * count reaches zero.
227 */
228void
229BSP_mve_mcast_filter_accept_del(struct mveth_private *mp, unsigned char *enaddr);
230
231/*
232 * Shutdown hardware and clean out the rings
233 */
234void
235BSP_mve_stop_hw(struct mveth_private *mp);
236
237/* calls BSP_mve_stop_hw(), releases all resources and marks the interface
238 * as unused.
239 * RETURNS 0 on success, nonzero on failure.
240 * NOTE:   the handle MUST NOT be used after successful execution of this
241 *         routine.
242 */
243int
244BSP_mve_detach(struct mveth_private *mp);
245
246/*
247 * Enqueue a mbuf chain or a raw data buffer for transmission;
248 * RETURN: #bytes sent or -1 if there are not enough free descriptors
249 *
250 * If 'len' is <=0 then 'm_head' is assumed to point to a mbuf chain.
251 * OTOH, a raw data packet (or a different type of buffer)
252 * may be send (non-BSD driver) by pointing data_p to the start of
253 * the data and passing 'len' > 0.
254 * 'm_head' is passed back to the 'cleanup_txbuf()' callback.
255 *
256 * Comments: software cache-flushing incurs a penalty if the
257 *           packet cannot be queued since it is flushed anyways.
258 *           The algorithm is slightly more efficient in the normal
259 *                       case, though.
260 *
261 * RETURNS: # bytes enqueued to device for transmission or -1 if no
262 *          space in the TX ring was available.
263 */
264int
265BSP_mve_send_buf(struct mveth_private *mp, void *m_head, void *data_p, int len);
266
267/* Descriptor scavenger; cleanup the TX ring, passing all buffers
268 * that have been sent to the cleanup_tx() callback.
269 * This routine is called from BSP_mve_send_buf(), BSP_mve_init_hw(),
270 * BSP_mve_stop_hw().
271 *
272 * RETURNS: number of buffers processed.
273 */
274int
275BSP_mve_swipe_tx(struct mveth_private *mp);
276
277/* Retrieve all received buffers from the RX ring, replacing them
278 * by fresh ones (obtained from the alloc_rxbuf() callback). The
279 * received buffers are passed to consume_rxbuf().
280 *
281 * RETURNS: number of buffers processed.
282 */
283int
284BSP_mve_swipe_rx(struct mveth_private *mp);
285
286/* read ethernet address from hw to buffer */
287void
288BSP_mve_read_eaddr(struct mveth_private *mp, unsigned char *eaddr);
289
290/* read/write media word.
291 *   'cmd': can be SIOCGIFMEDIA, SIOCSIFMEDIA, 0 or 1. The latter
292 *          are aliased to the former for convenience.
293 *  'parg': pointer to media word.
294 *
295 * RETURNS: 0 on success, nonzero on error
296 *
297 * NOTE:    This routine is thread-safe.
298 */
299int
300BSP_mve_media_ioctl(struct mveth_private *mp, int cmd, int *parg);
301
302/* Interrupt related routines */
303
304/* Note: the BSP_mve_enable/disable/ack_irqs() entry points
305 *       are deprecated.
306 *       The newer API where the user passes a mask allows
307 *       for more selective control.
308 */
309
310/* Enable all supported interrupts at device */
311void
312BSP_mve_enable_irqs(struct mveth_private *mp);
313
314/* Disable all supported interrupts at device */
315void
316BSP_mve_disable_irqs(struct mveth_private *mp);
317
318/* Acknowledge (and clear) all supported interrupts.
319 * RETURNS: interrupts that were raised.
320 */
321uint32_t
322BSP_mve_ack_irqs(struct mveth_private *mp);
323
324/* Enable interrupts included in 'mask' (leaving
325 * already enabled interrupts on). If the mask
326 * includes bits that were not passed to the 'setup'
327 * routine then the behavior is undefined.
328 */
329void
330BSP_mve_enable_irq_mask(struct mveth_private *mp, uint32_t irq_mask);
331
332/* Disable interrupts included in 'mask' (leaving
333 * other ones that are currently enabled on). If the
334 * mask includes bits that were not passed to the 'setup'
335 * routine then the behavior is undefined.
336 *
337 * RETURNS: Bitmask of interrupts that were enabled upon entry
338 *          into this routine. This can be used to restore the
339 *          previous state.
340 */
341uint32_t
342BSP_mve_disable_irq_mask(struct mveth_private *mp, uint32_t irq_mask);
343
344/* Acknowledge and clear selected interrupts.
345 *
346 * RETURNS: All pending interrupts.
347 *
348 * NOTE:    Only pending interrupts contained in 'mask'
349 *          are cleared. Others are left pending.
350 *
351 *          This routine can be used to check for pending
352 *          interrupts (pass mask ==  0) or to clear all
353 *          interrupts (pass mask == -1).
354 */
355uint32_t
356BSP_mve_ack_irq_mask(struct mveth_private *mp, uint32_t mask);
357
358/* If the PHY link status changes then some
359 * internal settings in the ethernet controller's
360 * serial port need to be updated to match the
361 * PHY settings. Use this routine to perform the
362 * necessary steps after a link change has been
363 * detected.
364 *
365 * RETURNS: 0 on success, -1 if the PHY state
366 *          could not be determined.
367 *
368 *          The current state of the media as read
369 *          by BSP_mve_media_ioctl() is returned in
370 *          *pmedia.
371 *
372 * NOTE:    This routine calls BSP_mve_media_ioctl().
373 */
374int
375BSP_mve_ack_link_chg(struct mveth_private *mp, int *pmedia);
376
377/* Retrieve the driver daemon TID that was passed to
378 * BSP_mve_setup().
379 */
380
381rtems_id
382BSP_mve_get_tid(struct mveth_private *mp);
383
384/* Dump statistics to file (stdout if NULL)
385 *
386 * NOTE: this routine is not thread safe
387 */
388void
389BSP_mve_dump_stats(struct mveth_private *mp, FILE *f);
390
391/*
392 *
393 * Example driver task loop (note: no synchronization of
394 * buffer access shown!).
395 * RTEMS_EVENTx = 0,1 or 2 depending on IF unit.
396 *
397 *    / * setup (obtain handle) and initialize hw here * /
398 *
399 *    do {
400 *      / * ISR disables IRQs and posts event * /
401 *              rtems_event_receive( RTEMS_EVENTx, RTEMS_WAIT | RTEMS_EVENT_ANY, RTEMS_NO_TIMEOUT, &evs );
402 *              irqs = BSP_mve_ack_irqs(handle);
403 *      if ( irqs & BSP_MVE_IRQ_TX ) {
404 *                      BSP_mve_swipe_tx(handle); / * cleanup_txbuf() callback executed * /
405 *              }
406 *      if ( irqs & BSP_MVE_IRQ_RX ) {
407 *                      BSP_mve_swipe_rx(handle); / * alloc_rxbuf() and consume_rxbuf() executed * /
408 *              }
409 *              if ( irqs & BSP_MVE_IRQ_LINK ) {
410 *          / * update serial port settings from current link status * /
411 *          BSP_mve_ack_link_chg(handle, 0);
412 *              }
413 *              BSP_mve_enable_irqs(handle);
414 *    } while (1);
415 *
416 */
417
418#ifdef __cplusplus
419  }
420#endif
421
422#endif
Note: See TracBrowser for help on using the repository browser.