1 | #ifndef IF_TSEC_PUBLIC_INTERFACE_H |
---|
2 | #define IF_TSEC_PUBLIC_INTERFACE_H |
---|
3 | |
---|
4 | /* |
---|
5 | * Authorship |
---|
6 | * ---------- |
---|
7 | * This software ('mvme3100' RTEMS BSP) was created by |
---|
8 | * |
---|
9 | * Till Straumann <strauman@slac.stanford.edu>, 2005-2007, |
---|
10 | * Stanford Linear Accelerator Center, Stanford University. |
---|
11 | * |
---|
12 | * Acknowledgement of sponsorship |
---|
13 | * ------------------------------ |
---|
14 | * The 'mvme3100' BSP was produced by |
---|
15 | * the Stanford Linear Accelerator Center, Stanford University, |
---|
16 | * under Contract DE-AC03-76SFO0515 with the Department of Energy. |
---|
17 | * |
---|
18 | * Government disclaimer of liability |
---|
19 | * ---------------------------------- |
---|
20 | * Neither the United States nor the United States Department of Energy, |
---|
21 | * nor any of their employees, makes any warranty, express or implied, or |
---|
22 | * assumes any legal liability or responsibility for the accuracy, |
---|
23 | * completeness, or usefulness of any data, apparatus, product, or process |
---|
24 | * disclosed, or represents that its use would not infringe privately owned |
---|
25 | * rights. |
---|
26 | * |
---|
27 | * Stanford disclaimer of liability |
---|
28 | * -------------------------------- |
---|
29 | * Stanford University makes no representations or warranties, express or |
---|
30 | * implied, nor assumes any liability for the use of this software. |
---|
31 | * |
---|
32 | * Stanford disclaimer of copyright |
---|
33 | * -------------------------------- |
---|
34 | * Stanford University, owner of the copyright, hereby disclaims its |
---|
35 | * copyright and all other rights in this software. Hence, anyone may |
---|
36 | * freely use it for any purpose without restriction. |
---|
37 | * |
---|
38 | * Maintenance of notices |
---|
39 | * ---------------------- |
---|
40 | * In the interest of clarity regarding the origin and status of this |
---|
41 | * SLAC software, this and all the preceding Stanford University notices |
---|
42 | * are to remain affixed to any copy or derivative of this software made |
---|
43 | * or distributed by the recipient and are to be affixed to any copy of |
---|
44 | * software made or distributed by the recipient that contains a copy or |
---|
45 | * derivative of this software. |
---|
46 | * |
---|
47 | * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03 |
---|
48 | */ |
---|
49 | |
---|
50 | #include <rtems.h> |
---|
51 | #include <stdio.h> |
---|
52 | |
---|
53 | #ifdef __cplusplus |
---|
54 | extern "C" { |
---|
55 | #endif |
---|
56 | |
---|
57 | /* Opaque driver handle */ |
---|
58 | struct tsec_private; |
---|
59 | |
---|
60 | /********** Low-level Driver API ****************/ |
---|
61 | |
---|
62 | /* |
---|
63 | * This API provides driver access to applications that |
---|
64 | * want to use e.g., the second ethernet interface |
---|
65 | * independently from the BSD TCP/IP stack. E.g., for |
---|
66 | * raw ethernet packet communication... |
---|
67 | */ |
---|
68 | |
---|
69 | /* |
---|
70 | * Setup an interface. |
---|
71 | * Allocates resources for descriptor rings and sets up the driver software structure. |
---|
72 | * |
---|
73 | * Arguments: |
---|
74 | * unit: |
---|
75 | * interface # (1..2). The interface must not be attached to BSD already. |
---|
76 | * |
---|
77 | * driver_tid: |
---|
78 | * ISR posts RTEMS event # ('unit' - 1) to task with ID 'driver_tid' and disables interrupts |
---|
79 | * from this interface. |
---|
80 | * |
---|
81 | * void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred): |
---|
82 | * Pointer to user-supplied callback to release a buffer that had been sent |
---|
83 | * by BSP_tsec_send_buf() earlier. The callback is passed 'cleanup_txbuf_arg' |
---|
84 | * and a flag indicating whether the send had been successful. |
---|
85 | * The driver no longer accesses 'user_buf' after invoking this callback. |
---|
86 | * CONTEXT: This callback is executed either by BSP_tsec_swipe_tx() or |
---|
87 | * BSP_tsec_send_buf(), BSP_tsec_init_hw(), BSP_tsec_stop_hw() (the latter |
---|
88 | * ones calling BSP_tsec_swipe_tx()). |
---|
89 | * void *cleanup_txbuf_arg: |
---|
90 | * Closure argument that is passed on to 'cleanup_txbuf()' callback; |
---|
91 | * |
---|
92 | * void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr), |
---|
93 | * Pointer to user-supplied callback to allocate a buffer for subsequent |
---|
94 | * insertion into the RX ring by the driver. |
---|
95 | * RETURNS: opaque handle to the buffer (which may be a more complex object |
---|
96 | * such as an 'mbuf'). The handle is not used by the driver directly |
---|
97 | * but passed back to the 'consume_rxbuf()' callback. |
---|
98 | * Size of the available data area and pointer to buffer's data area |
---|
99 | * in '*psize' and '*p_data_area', respectively. |
---|
100 | * If no buffer is available, this routine should return NULL in which |
---|
101 | * case the driver drops the last packet and re-uses the last buffer |
---|
102 | * instead of handing it out to 'consume_rxbuf()'. |
---|
103 | * CONTEXT: Called when initializing the RX ring (BSP_tsec_init_hw()) or when |
---|
104 | * swiping it (BSP_tsec_swipe_rx()). |
---|
105 | * |
---|
106 | * |
---|
107 | * void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len); |
---|
108 | * Pointer to user-supplied callback to pass a received buffer back to |
---|
109 | * the user. The driver no longer accesses the buffer after invoking this |
---|
110 | * callback (with 'len'>0, see below). 'user_buf' is the buffer handle |
---|
111 | * previously generated by 'alloc_rxbuf()'. |
---|
112 | * The callback is passed 'cleanup_rxbuf_arg' and a 'len' |
---|
113 | * argument giving the number of bytes that were received. |
---|
114 | * 'len' may be <=0 in which case the 'user_buf' argument is NULL. |
---|
115 | * 'len' == 0 means that the last 'alloc_rxbuf()' had failed, |
---|
116 | * 'len' < 0 indicates a receiver error. In both cases, the last packet |
---|
117 | * was dropped/missed and the last buffer will be re-used by the driver. |
---|
118 | * NOTE: the data are 'prefixed' with two bytes, i.e., the ethernet packet header |
---|
119 | * is stored at offset 2 in the buffer's data area. Also, the FCS (4 bytes) |
---|
120 | * is appended. 'len' accounts for both. |
---|
121 | * CONTEXT: Called from BSP_tsec_swipe_rx(). |
---|
122 | * void *cleanup_rxbuf_arg: |
---|
123 | * Closure argument that is passed on to 'consume_rxbuf()' callback; |
---|
124 | * |
---|
125 | * rx_ring_size, tx_ring_size: |
---|
126 | * How many big to make the RX and TX descriptor rings. Note that the sizes |
---|
127 | * may be 0 in which case a reasonable default will be used. |
---|
128 | * If either ring size is < 0 then the RX or TX will be disabled. |
---|
129 | * Note that it is illegal in this case to use BSP_tsec_swipe_rx() or |
---|
130 | * BSP_tsec_swipe_tx(), respectively. |
---|
131 | * |
---|
132 | * irq_mask: |
---|
133 | * Interrupts to enable. OR of flags from above. |
---|
134 | * |
---|
135 | */ |
---|
136 | struct tsec_private * |
---|
137 | BSP_tsec_setup( |
---|
138 | int unit, |
---|
139 | rtems_id driver_tid, |
---|
140 | void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred), |
---|
141 | void *cleanup_txbuf_arg, |
---|
142 | void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr), |
---|
143 | void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len), |
---|
144 | void *consume_rxbuf_arg, |
---|
145 | int rx_ring_size, |
---|
146 | int tx_ring_size, |
---|
147 | int irq_mask |
---|
148 | ); |
---|
149 | |
---|
150 | /* |
---|
151 | * Descriptor scavenger; cleanup the TX ring, passing all buffers |
---|
152 | * that have been sent to the cleanup_tx() callback. |
---|
153 | * This routine is called from BSP_tsec_send_buf(), BSP_tsec_init_hw(), |
---|
154 | * BSP_tsec_stop_hw(). |
---|
155 | * |
---|
156 | * RETURNS: number of buffers processed. |
---|
157 | */ |
---|
158 | |
---|
159 | int |
---|
160 | BSP_tsec_swipe_tx(struct tsec_private *mp); |
---|
161 | |
---|
162 | |
---|
163 | /* |
---|
164 | * Reset statistics counters. |
---|
165 | */ |
---|
166 | void |
---|
167 | BSP_tsec_reset_stats(struct tsec_private *mp); |
---|
168 | |
---|
169 | /* |
---|
170 | * Initialize interface hardware |
---|
171 | * |
---|
172 | * 'mp' handle obtained by from BSP_tsec_setup(). |
---|
173 | * 'promisc' whether to set promiscuous flag. |
---|
174 | * 'enaddr' pointer to six bytes with MAC address. Read |
---|
175 | * from the device if NULL. |
---|
176 | */ |
---|
177 | void |
---|
178 | BSP_tsec_init_hw(struct tsec_private *mp, int promisc, unsigned char *enaddr); |
---|
179 | |
---|
180 | /* |
---|
181 | * Dump statistics to FILE 'f'. If NULL, stdout is used. |
---|
182 | */ |
---|
183 | void |
---|
184 | BSP_tsec_dump_stats(struct tsec_private *mp, FILE *f); |
---|
185 | |
---|
186 | /* |
---|
187 | * Shutdown hardware and clean out the rings |
---|
188 | */ |
---|
189 | void |
---|
190 | BSP_tsec_stop_hw(struct tsec_private *mp); |
---|
191 | |
---|
192 | /* |
---|
193 | * calls BSP_tsec_stop_hw(), releases all resources and marks the interface |
---|
194 | * as unused. |
---|
195 | * RETURNS 0 on success, nonzero on failure. |
---|
196 | * NOTE: the handle MUST NOT be used after successful execution of this |
---|
197 | * routine. |
---|
198 | */ |
---|
199 | int |
---|
200 | BSP_tsec_detach(struct tsec_private *mp); |
---|
201 | |
---|
202 | /* |
---|
203 | * Enqueue a mbuf chain or a raw data buffer for transmission; |
---|
204 | * RETURN: #bytes sent or -1 if there are not enough free descriptors |
---|
205 | * |
---|
206 | * If 'len' is <=0 then 'm_head' is assumed to point to a mbuf chain. |
---|
207 | * OTOH, a raw data packet (or a different type of buffer) |
---|
208 | * may be sent (non-BSD driver) by pointing data_p to the start of |
---|
209 | * the data and passing 'len' > 0. |
---|
210 | * 'm_head' is passed back to the 'cleanup_txbuf()' callback. |
---|
211 | * |
---|
212 | * Comments: software cache-flushing incurs a penalty if the |
---|
213 | * packet cannot be queued since it is flushed anyways. |
---|
214 | * The algorithm is slightly more efficient in the normal |
---|
215 | * case, though. |
---|
216 | * |
---|
217 | * RETURNS: # bytes enqueued to device for transmission or -1 if no |
---|
218 | * space in the TX ring was available. |
---|
219 | */ |
---|
220 | |
---|
221 | int |
---|
222 | BSP_tsec_send_buf(struct tsec_private *mp, void *m_head, void *data_p, int len); |
---|
223 | |
---|
224 | /* |
---|
225 | * Retrieve all received buffers from the RX ring, replacing them |
---|
226 | * by fresh ones (obtained from the alloc_rxbuf() callback). The |
---|
227 | * received buffers are passed to consume_rxbuf(). |
---|
228 | * |
---|
229 | * RETURNS: number of buffers processed. |
---|
230 | */ |
---|
231 | int |
---|
232 | BSP_tsec_swipe_rx(struct tsec_private *mp); |
---|
233 | |
---|
234 | /* read ethernet address from hw to buffer */ |
---|
235 | void |
---|
236 | BSP_tsec_read_eaddr(struct tsec_private *mp, unsigned char *eaddr); |
---|
237 | |
---|
238 | /* Read MII register */ |
---|
239 | uint32_t |
---|
240 | BSP_tsec_mdio_rd(struct tsec_private *mp, unsigned reg); |
---|
241 | |
---|
242 | /* Write MII register */ |
---|
243 | int |
---|
244 | BSP_tsec_mdio_wr(struct tsec_private *mp, unsigned reg, uint32_t val); |
---|
245 | |
---|
246 | /* |
---|
247 | * read/write media word. |
---|
248 | * 'cmd': can be SIOCGIFMEDIA, SIOCSIFMEDIA, 0 or 1. The latter |
---|
249 | * are aliased to the former for convenience. |
---|
250 | * 'parg': pointer to media word. |
---|
251 | * |
---|
252 | * RETURNS: 0 on success, nonzero on error |
---|
253 | */ |
---|
254 | int |
---|
255 | BSP_tsec_media_ioctl(struct tsec_private *mp, int cmd, int *parg); |
---|
256 | |
---|
257 | /* Interrupt related routines */ |
---|
258 | |
---|
259 | /* |
---|
260 | * When it comes to interrupts the chip has two rather |
---|
261 | * annoying features: |
---|
262 | * 1 once an IRQ is pending, clearing the IMASK does not |
---|
263 | * de-assert the interrupt line. |
---|
264 | * 2 the chip has three physical interrupt lines even though |
---|
265 | * all events are reported in a single register. Rather |
---|
266 | * useless; we must hook 3 ISRs w/o any real benefit. |
---|
267 | * In fact, it makes our life a bit more difficult: |
---|
268 | * |
---|
269 | * Hence, for (1) we would have to mask interrupts at the PIC |
---|
270 | * but to re-enable them we would have to do that three times |
---|
271 | * because of (2). |
---|
272 | * |
---|
273 | * Therefore, we take the following approach: |
---|
274 | * |
---|
275 | * ISR masks all interrupts on the TSEC, acks/clears them |
---|
276 | * and stores the acked irqs in the device struct where |
---|
277 | * it is picked up by BSP_tsec_ack_irqs(). |
---|
278 | * Since all interrupts are disabled until the daemon |
---|
279 | * re-enables them after calling BSP_tsec_ack_irqs() |
---|
280 | * no interrupts are lost. |
---|
281 | * |
---|
282 | * BUT: NO isr (including PHY isrs) MUST INTERRUPT ANY |
---|
283 | * OTHER ONE, i.e., they all must have the same |
---|
284 | * priority. Otherwise, integrity of the cached |
---|
285 | * irq_pending variable may be compromised. |
---|
286 | */ |
---|
287 | |
---|
288 | /* Enable interrupts at device */ |
---|
289 | void |
---|
290 | BSP_tsec_enable_irqs(struct tsec_private *mp); |
---|
291 | |
---|
292 | /* Disable interrupts at device */ |
---|
293 | void |
---|
294 | BSP_tsec_disable_irqs(struct tsec_private *mp); |
---|
295 | |
---|
296 | /* |
---|
297 | * Acknowledge (and clear) interrupts. |
---|
298 | * RETURNS: interrupts that were raised. |
---|
299 | */ |
---|
300 | uint32_t |
---|
301 | BSP_tsec_ack_irqs(struct tsec_private *mp); |
---|
302 | |
---|
303 | /* Retrieve the driver daemon TID that was passed to |
---|
304 | * BSP_tsec_setup(). |
---|
305 | */ |
---|
306 | |
---|
307 | rtems_id |
---|
308 | BSP_tsec_get_tid(struct tsec_private *mp); |
---|
309 | |
---|
310 | struct tsec_private * |
---|
311 | BSP_tsec_getp(unsigned index); |
---|
312 | |
---|
313 | /* |
---|
314 | * |
---|
315 | * Example driver task loop (note: no synchronization of |
---|
316 | * buffer access shown!). |
---|
317 | * RTEMS_EVENTx = 0,1 or 2 depending on IF unit. |
---|
318 | * |
---|
319 | * / * setup (obtain handle) and initialize hw here * / |
---|
320 | * |
---|
321 | * do { |
---|
322 | * / * ISR disables IRQs and posts event * / |
---|
323 | * rtems_event_receive( RTEMS_EVENTx, RTEMS_WAIT | RTEMS_EVENT_ANY, RTEMS_NO_TIMEOUT, &evs ); |
---|
324 | * irqs = BSP_tsec_ack_irqs(handle); |
---|
325 | * if ( irqs & BSP_TSEC_IRQ_TX ) { |
---|
326 | * BSP_tsec_swipe_tx(handle); / * cleanup_txbuf() callback executed * / |
---|
327 | * } |
---|
328 | * if ( irqs & BSP_TSEC_IRQ_RX ) { |
---|
329 | * BSP_tsec_swipe_rx(handle); / * alloc_rxbuf() and consume_rxbuf() executed * / |
---|
330 | * } |
---|
331 | * BSP_tsec_enable_irqs(handle); |
---|
332 | * } while (1); |
---|
333 | * |
---|
334 | */ |
---|
335 | |
---|
336 | /* PUBLIC RTEMS BSDNET ATTACH FUNCTION */ |
---|
337 | struct rtems_bsdnet_ifconfig; |
---|
338 | |
---|
339 | int |
---|
340 | rtems_tsec_attach(struct rtems_bsdnet_ifconfig *ifcfg, int attaching); |
---|
341 | |
---|
342 | #ifdef __cplusplus |
---|
343 | } |
---|
344 | #endif |
---|
345 | |
---|
346 | #endif |
---|