RTEMS: bsps/powerpc/beatnik/include/bsp/if_mve_pub.h Source File

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
if_mve_pub.h
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
246int
247BSP_mve_send_buf_raw(struct mveth_private *mp, void *head_p, int h_len,
248 void *data_p, int d_len);
249
250/*
251 * Enqueue a mbuf chain or a raw data buffer for transmission;
252 * RETURN: #bytes sent or -1 if there are not enough free descriptors
253 *
254 * If 'len' is <=0 then 'm_head' is assumed to point to a mbuf chain.
255 * OTOH, a raw data packet (or a different type of buffer)
256 * may be send (non-BSD driver) by pointing data_p to the start of
257 * the data and passing 'len' > 0.
258 * 'm_head' is passed back to the 'cleanup_txbuf()' callback.
259 *
260 * Comments: software cache-flushing incurs a penalty if the
261 * packet cannot be queued since it is flushed anyways.
262 * The algorithm is slightly more efficient in the normal
263 * case, though.
264 *
265 * RETURNS: # bytes enqueued to device for transmission or -1 if no
266 * space in the TX ring was available.
267 */
268int
269BSP_mve_send_buf(struct mveth_private *mp, void *m_head, void *data_p, int len);
270
271/* Descriptor scavenger; cleanup the TX ring, passing all buffers
272 * that have been sent to the cleanup_tx() callback.
273 * This routine is called from BSP_mve_send_buf(), BSP_mve_init_hw(),
274 * BSP_mve_stop_hw().
275 *
276 * RETURNS: number of buffers processed.
277 */
278int
279BSP_mve_swipe_tx(struct mveth_private *mp);
280
281/* Retrieve all received buffers from the RX ring, replacing them
282 * by fresh ones (obtained from the alloc_rxbuf() callback). The
283 * received buffers are passed to consume_rxbuf().
284 *
285 * RETURNS: number of buffers processed.
286 */
287int
288BSP_mve_swipe_rx(struct mveth_private *mp);
289
290/* read ethernet address from hw to buffer */
291void
292BSP_mve_read_eaddr(struct mveth_private *mp, unsigned char *eaddr);
293
294/* read/write media word.
295 * 'cmd': can be SIOCGIFMEDIA, SIOCSIFMEDIA, 0 or 1. The latter
296 * are aliased to the former for convenience.
297 * 'parg': pointer to media word.
298 *
299 * RETURNS: 0 on success, nonzero on error
300 *
301 * NOTE: This routine is thread-safe.
302 */
303int
304BSP_mve_media_ioctl(struct mveth_private *mp, int cmd, int *parg);
305
306/* Interrupt related routines */
307
308/* Note: the BSP_mve_enable/disable/ack_irqs() entry points
309 * are deprecated.
310 * The newer API where the user passes a mask allows
311 * for more selective control.
312 */
313
314/* Enable all supported interrupts at device */
315void
316BSP_mve_enable_irqs(struct mveth_private *mp);
317
318/* Disable all supported interrupts at device */
319void
320BSP_mve_disable_irqs(struct mveth_private *mp);
321
322/* Acknowledge (and clear) all supported interrupts.
323 * RETURNS: interrupts that were raised.
324 */
325uint32_t
326BSP_mve_ack_irqs(struct mveth_private *mp);
327
328/* Enable interrupts included in 'mask' (leaving
329 * already enabled interrupts on). If the mask
330 * includes bits that were not passed to the 'setup'
331 * routine then the behavior is undefined.
332 */
333void
334BSP_mve_enable_irq_mask(struct mveth_private *mp, uint32_t irq_mask);
335
336/* Disable interrupts included in 'mask' (leaving
337 * other ones that are currently enabled on). If the
338 * mask includes bits that were not passed to the 'setup'
339 * routine then the behavior is undefined.
340 *
341 * RETURNS: Bitmask of interrupts that were enabled upon entry
342 * into this routine. This can be used to restore the
343 * previous state.
344 */
345uint32_t
346BSP_mve_disable_irq_mask(struct mveth_private *mp, uint32_t irq_mask);
347
348/* Acknowledge and clear selected interrupts.
349 *
350 * RETURNS: All pending interrupts.
351 *
352 * NOTE: Only pending interrupts contained in 'mask'
353 * are cleared. Others are left pending.
354 *
355 * This routine can be used to check for pending
356 * interrupts (pass mask == 0) or to clear all
357 * interrupts (pass mask == -1).
358 */
359uint32_t
360BSP_mve_ack_irq_mask(struct mveth_private *mp, uint32_t mask);
361
362/* If the PHY link status changes then some
363 * internal settings in the ethernet controller's
364 * serial port need to be updated to match the
365 * PHY settings. Use this routine to perform the
366 * necessary steps after a link change has been
367 * detected.
368 *
369 * RETURNS: 0 on success, -1 if the PHY state
370 * could not be determined.
371 *
372 * The current state of the media as read
373 * by BSP_mve_media_ioctl() is returned in
374 * *pmedia.
375 *
376 * NOTE: This routine calls BSP_mve_media_ioctl().
377 */
378int
379BSP_mve_ack_link_chg(struct mveth_private *mp, int *pmedia);
380
381/* Retrieve the driver daemon TID that was passed to
382 * BSP_mve_setup().
383 */
384
385 rtems_id
386BSP_mve_get_tid(struct mveth_private *mp);
387
388/* Dump statistics to file (stdout if NULL)
389 *
390 * NOTE: this routine is not thread safe
391 */
392void
393BSP_mve_dump_stats(struct mveth_private *mp, FILE *f);
394
395/*
396 *
397 * Example driver task loop (note: no synchronization of
398 * buffer access shown!).
399 * RTEMS_EVENTx = 0,1 or 2 depending on IF unit.
400 *
401 * / * setup (obtain handle) and initialize hw here * /
402 *
403 * do {
404 * / * ISR disables IRQs and posts event * /
405 * rtems_event_receive( RTEMS_EVENTx, RTEMS_WAIT | RTEMS_EVENT_ANY, RTEMS_NO_TIMEOUT, &evs );
406 * irqs = BSP_mve_ack_irqs(handle);
407 * if ( irqs & BSP_MVE_IRQ_TX ) {
408 * BSP_mve_swipe_tx(handle); / * cleanup_txbuf() callback executed * /
409 * }
410 * if ( irqs & BSP_MVE_IRQ_RX ) {
411 * BSP_mve_swipe_rx(handle); / * alloc_rxbuf() and consume_rxbuf() executed * /
412 * }
413 * if ( irqs & BSP_MVE_IRQ_LINK ) {
414 * / * update serial port settings from current link status * /
415 * BSP_mve_ack_link_chg(handle, 0);
416 * }
417 * BSP_mve_enable_irqs(handle);
418 * } while (1);
419 *
420 */
421
422#ifdef __cplusplus
423 }
424#endif
425
426#endif
rtems_id
Objects_Id rtems_id
Used to manage and manipulate RTEMS object identifiers.
Definition: types.h:83
rtems.h
rtems_bsdnet_early_link_check_ops
Definition: early_enet_link_status.h:14