diff options
Diffstat (limited to 'c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h')
| -rw-r--r-- | c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h b/c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h new file mode 100644 index 0000000000..da3f2bc1a7 --- /dev/null +++ b/c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h @@ -0,0 +1,346 @@ +#ifndef IF_TSEC_PUBLIC_INTERFACE_H +#define IF_TSEC_PUBLIC_INTERFACE_H + +/* + * Authorship + * ---------- + * This software ('mvme3100' RTEMS BSP) was created by + * + * Till Straumann <strauman@slac.stanford.edu>, 2005-2007, + * Stanford Linear Accelerator Center, Stanford University. + * + * Acknowledgement of sponsorship + * ------------------------------ + * The 'mvme3100' BSP was produced by + * the Stanford Linear Accelerator Center, Stanford University, + * under Contract DE-AC03-76SFO0515 with the Department of Energy. + * + * Government disclaimer of liability + * ---------------------------------- + * Neither the United States nor the United States Department of Energy, + * nor any of their employees, makes any warranty, express or implied, or + * assumes any legal liability or responsibility for the accuracy, + * completeness, or usefulness of any data, apparatus, product, or process + * disclosed, or represents that its use would not infringe privately owned + * rights. + * + * Stanford disclaimer of liability + * -------------------------------- + * Stanford University makes no representations or warranties, express or + * implied, nor assumes any liability for the use of this software. + * + * Stanford disclaimer of copyright + * -------------------------------- + * Stanford University, owner of the copyright, hereby disclaims its + * copyright and all other rights in this software. Hence, anyone may + * freely use it for any purpose without restriction. + * + * Maintenance of notices + * ---------------------- + * In the interest of clarity regarding the origin and status of this + * SLAC software, this and all the preceding Stanford University notices + * are to remain affixed to any copy or derivative of this software made + * or distributed by the recipient and are to be affixed to any copy of + * software made or distributed by the recipient that contains a copy or + * derivative of this software. + * + * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03 + */ + +#include <rtems.h> +#include <stdio.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* Opaque driver handle */ +struct tsec_private; + +/********** Low-level Driver API ****************/ + +/* + * This API provides driver access to applications that + * want to use e.g., the second ethernet interface + * independently from the BSD TCP/IP stack. E.g., for + * raw ethernet packet communication... + */ + +/* + * Setup an interface. + * Allocates resources for descriptor rings and sets up the driver software structure. + * + * Arguments: + * unit: + * interface # (1..2). The interface must not be attached to BSD already. + * + * driver_tid: + * ISR posts RTEMS event # ('unit' - 1) to task with ID 'driver_tid' and disables interrupts + * from this interface. + * + * void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred): + * Pointer to user-supplied callback to release a buffer that had been sent + * by BSP_tsec_send_buf() earlier. The callback is passed 'cleanup_txbuf_arg' + * and a flag indicating whether the send had been successful. + * The driver no longer accesses 'user_buf' after invoking this callback. + * CONTEXT: This callback is executed either by BSP_tsec_swipe_tx() or + * BSP_tsec_send_buf(), BSP_tsec_init_hw(), BSP_tsec_stop_hw() (the latter + * ones calling BSP_tsec_swipe_tx()). + * void *cleanup_txbuf_arg: + * Closure argument that is passed on to 'cleanup_txbuf()' callback; + * + * void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr), + * Pointer to user-supplied callback to allocate a buffer for subsequent + * insertion into the RX ring by the driver. + * RETURNS: opaque handle to the buffer (which may be a more complex object + * such as an 'mbuf'). The handle is not used by the driver directly + * but passed back to the 'consume_rxbuf()' callback. + * Size of the available data area and pointer to buffer's data area + * in '*psize' and '*p_data_area', respectively. + * If no buffer is available, this routine should return NULL in which + * case the driver drops the last packet and re-uses the last buffer + * instead of handing it out to 'consume_rxbuf()'. + * CONTEXT: Called when initializing the RX ring (BSP_tsec_init_hw()) or when + * swiping it (BSP_tsec_swipe_rx()). + * + * + * void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len); + * Pointer to user-supplied callback to pass a received buffer back to + * the user. The driver no longer accesses the buffer after invoking this + * callback (with 'len'>0, see below). 'user_buf' is the buffer handle + * previously generated by 'alloc_rxbuf()'. + * The callback is passed 'cleanup_rxbuf_arg' and a 'len' + * argument giving the number of bytes that were received. + * 'len' may be <=0 in which case the 'user_buf' argument is NULL. + * 'len' == 0 means that the last 'alloc_rxbuf()' had failed, + * 'len' < 0 indicates a receiver error. In both cases, the last packet + * was dropped/missed and the last buffer will be re-used by the driver. + * NOTE: the data are 'prefixed' with two bytes, i.e., the ethernet packet header + * is stored at offset 2 in the buffer's data area. Also, the FCS (4 bytes) + * is appended. 'len' accounts for both. + * CONTEXT: Called from BSP_tsec_swipe_rx(). + * void *cleanup_rxbuf_arg: + * Closure argument that is passed on to 'consume_rxbuf()' callback; + * + * rx_ring_size, tx_ring_size: + * How many big to make the RX and TX descriptor rings. Note that the sizes + * may be 0 in which case a reasonable default will be used. + * If either ring size is < 0 then the RX or TX will be disabled. + * Note that it is illegal in this case to use BSP_tsec_swipe_rx() or + * BSP_tsec_swipe_tx(), respectively. + * + * irq_mask: + * Interrupts to enable. OR of flags from above. + * + */ +struct tsec_private * +BSP_tsec_setup( + int unit, + rtems_id driver_tid, + void (*cleanup_txbuf)(void *user_buf, void *cleanup_txbuf_arg, int error_on_tx_occurred), + void *cleanup_txbuf_arg, + void *(*alloc_rxbuf)(int *p_size, uintptr_t *p_data_addr), + void (*consume_rxbuf)(void *user_buf, void *consume_rxbuf_arg, int len), + void *consume_rxbuf_arg, + int rx_ring_size, + int tx_ring_size, + int irq_mask +); + +/* + * Descriptor scavenger; cleanup the TX ring, passing all buffers + * that have been sent to the cleanup_tx() callback. + * This routine is called from BSP_tsec_send_buf(), BSP_tsec_init_hw(), + * BSP_tsec_stop_hw(). + * + * RETURNS: number of buffers processed. + */ + +int +BSP_tsec_swipe_tx(struct tsec_private *mp); + + +/* + * Reset statistics counters. + */ +void +BSP_tsec_reset_stats(struct tsec_private *mp); + +/* + * Initialize interface hardware + * + * 'mp' handle obtained by from BSP_tsec_setup(). + * 'promisc' whether to set promiscuous flag. + * 'enaddr' pointer to six bytes with MAC address. Read + * from the device if NULL. + */ +void +BSP_tsec_init_hw(struct tsec_private *mp, int promisc, unsigned char *enaddr); + +/* + * Dump statistics to FILE 'f'. If NULL, stdout is used. + */ +void +BSP_tsec_dump_stats(struct tsec_private *mp, FILE *f); + +/* + * Shutdown hardware and clean out the rings + */ +void +BSP_tsec_stop_hw(struct tsec_private *mp); + +/* + * calls BSP_tsec_stop_hw(), releases all resources and marks the interface + * as unused. + * RETURNS 0 on success, nonzero on failure. + * NOTE: the handle MUST NOT be used after successful execution of this + * routine. + */ +int +BSP_tsec_detach(struct tsec_private *mp); + +/* + * Enqueue a mbuf chain or a raw data buffer for transmission; + * RETURN: #bytes sent or -1 if there are not enough free descriptors + * + * If 'len' is <=0 then 'm_head' is assumed to point to a mbuf chain. + * OTOH, a raw data packet (or a different type of buffer) + * may be sent (non-BSD driver) by pointing data_p to the start of + * the data and passing 'len' > 0. + * 'm_head' is passed back to the 'cleanup_txbuf()' callback. + * + * Comments: software cache-flushing incurs a penalty if the + * packet cannot be queued since it is flushed anyways. + * The algorithm is slightly more efficient in the normal + * case, though. + * + * RETURNS: # bytes enqueued to device for transmission or -1 if no + * space in the TX ring was available. + */ + +int +BSP_tsec_send_buf(struct tsec_private *mp, void *m_head, void *data_p, int len); + +/* + * Retrieve all received buffers from the RX ring, replacing them + * by fresh ones (obtained from the alloc_rxbuf() callback). The + * received buffers are passed to consume_rxbuf(). + * + * RETURNS: number of buffers processed. + */ +int +BSP_tsec_swipe_rx(struct tsec_private *mp); + +/* read ethernet address from hw to buffer */ +void +BSP_tsec_read_eaddr(struct tsec_private *mp, unsigned char *eaddr); + +/* Read MII register */ +uint32_t +BSP_tsec_mdio_rd(struct tsec_private *mp, unsigned reg); + +/* Write MII register */ +int +BSP_tsec_mdio_wr(struct tsec_private *mp, unsigned reg, uint32_t val); + +/* + * read/write media word. + * 'cmd': can be SIOCGIFMEDIA, SIOCSIFMEDIA, 0 or 1. The latter + * are aliased to the former for convenience. + * 'parg': pointer to media word. + * + * RETURNS: 0 on success, nonzero on error + */ +int +BSP_tsec_media_ioctl(struct tsec_private *mp, int cmd, int *parg); + +/* Interrupt related routines */ + +/* + * When it comes to interrupts the chip has two rather + * annoying features: + * 1 once an IRQ is pending, clearing the IMASK does not + * de-assert the interrupt line. + * 2 the chip has three physical interrupt lines even though + * all events are reported in a single register. Rather + * useless; we must hook 3 ISRs w/o any real benefit. + * In fact, it makes our life a bit more difficult: + * + * Hence, for (1) we would have to mask interrupts at the PIC + * but to re-enable them we would have to do that three times + * because of (2). + * + * Therefore, we take the following approach: + * + * ISR masks all interrupts on the TSEC, acks/clears them + * and stores the acked irqs in the device struct where + * it is picked up by BSP_tsec_ack_irqs(). + * Since all interrupts are disabled until the daemon + * re-enables them after calling BSP_tsec_ack_irqs() + * no interrupts are lost. + * + * BUT: NO isr (including PHY isrs) MUST INTERRUPT ANY + * OTHER ONE, i.e., they all must have the same + * priority. Otherwise, integrity of the cached + * irq_pending variable may be compromised. + */ + +/* Enable interrupts at device */ +void +BSP_tsec_enable_irqs(struct tsec_private *mp); + +/* Disable interrupts at device */ +void +BSP_tsec_disable_irqs(struct tsec_private *mp); + +/* + * Acknowledge (and clear) interrupts. + * RETURNS: interrupts that were raised. + */ +uint32_t +BSP_tsec_ack_irqs(struct tsec_private *mp); + +/* Retrieve the driver daemon TID that was passed to + * BSP_tsec_setup(). + */ + +rtems_id +BSP_tsec_get_tid(struct tsec_private *mp); + +struct tsec_private * +BSP_tsec_getp(unsigned index); + +/* + * + * Example driver task loop (note: no synchronization of + * buffer access shown!). + * RTEMS_EVENTx = 0,1 or 2 depending on IF unit. + * + * / * setup (obtain handle) and initialize hw here * / + * + * do { + * / * ISR disables IRQs and posts event * / + * rtems_event_receive( RTEMS_EVENTx, RTEMS_WAIT | RTEMS_EVENT_ANY, RTEMS_NO_TIMEOUT, &evs ); + * irqs = BSP_tsec_ack_irqs(handle); + * if ( irqs & BSP_TSEC_IRQ_TX ) { + * BSP_tsec_swipe_tx(handle); / * cleanup_txbuf() callback executed * / + * } + * if ( irqs & BSP_TSEC_IRQ_RX ) { + * BSP_tsec_swipe_rx(handle); / * alloc_rxbuf() and consume_rxbuf() executed * / + * } + * BSP_tsec_enable_irqs(handle); + * } while (1); + * + */ + +/* PUBLIC RTEMS BSDNET ATTACH FUNCTION */ +struct rtems_bsdnet_ifconfig; + +int +rtems_tsec_attach(struct rtems_bsdnet_ifconfig *ifcfg, int attaching); + +#ifdef __cplusplus +} +#endif + +#endif |