/** * @file * * @ingroup powerpc_iftsecpub * * @brief IF_TSEC_PUB Support */ #ifndef IF_TSEC_PUBLIC_INTERFACE_H #define IF_TSEC_PUBLIC_INTERFACE_H /* * Authorship * ---------- * This software ('mvme3100' RTEMS BSP) was created by * * Till Straumann , 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 #include #include #ifdef __cplusplus extern "C" { #endif /* Opaque driver handle */ struct tsec_private; /********** Low-level Driver API ****************/ /** * @defgroup powerpc_iftsecpub Low-level Driver API * * @ingroup RTEMSBSPsPowerPCMVME3100 * * @brief 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... */ #define TSEC_TXIRQ ( (1<<(31-9)) | (1<<(31-11)) ) #define TSEC_RXIRQ ( (1<<(31-0)) | (1<<(31- 3)) | (1<<(31-24)) ) #define TSEC_LKIRQ ( 1<<(31- 4) ) /* * 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 ); /* * Alternate 'setup' routine allowing the user to install an ISR rather * than a task ID. * All parameters (other than 'isr' / 'isr_arg') and the return value * are identical to the BSP_tsec_setup() entry point. */ struct tsec_private * BSP_tsec_setup_1( int unit, void (*isr)(void *isr_arg), void * isr_arg, 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. * NOTE: multicast filter is cleared by this routine. */ void BSP_tsec_init_hw(struct tsec_private *mp, int promisc, unsigned char *enaddr); /* * Clear multicast hash filter. No multicast frames are accepted * after executing this routine (unless the hardware was initialized * in 'promiscuous' mode). * * Reset reference count for all hash-table entries * to zero (see BSP_tsec_mcast_filter_accept_del()). */ void BSP_tsec_mcast_filter_clear(struct tsec_private *mp); /* * Program multicast filter to accept all multicast frames. * * Increment reference count for all hash-table entries * by one (see BSP_tsec_mcast_filter_accept_del()). */ void BSP_tsec_mcast_filter_accept_all(struct tsec_private *mp); /* * Add a MAC address to the multicast filter and increment * the reference count for the matching hash-table entry * (see BSP_tsec_mcast_filter_accept_del()). * * Existing entries are not changed but note that * the filter is imperfect, i.e., multiple MAC addresses * may alias to a single filter entry. Hence software * filtering must still be performed. * */ void BSP_tsec_mcast_filter_accept_add(struct tsec_private *mp, unsigned char *enaddr); /* * Remove a MAC address from the (imperfec) multicast * filter. * Note that the driver maintains an internal reference * counter for each multicast hash. The hash-table * entry is only cleared when the reference count * reaches zero ('del' has been called the same * amount of times as 'add' for an address (or * any alias) that matches a given table entry. * BSP_tsec_mcast_filter_clear() resets all reference * counters to zero. */ void BSP_tsec_mcast_filter_accept_del(struct tsec_private *mp, 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. */ /* Note: the BSP_tsec_enable/disable/ack_irqs() entry points * are deprecated. * The newer API where the user passes a mask allows * for more selective control. */ /* 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); /* Enable interrupts included in 'mask' (leaving * already enabled interrupts on). If the mask includes * bits that were not passed to the 'setup' routine then * the behavior is undefined. */ void BSP_tsec_enable_irq_mask(struct tsec_private *mp, uint32_t irq_mask); /* Disable interrupts included in 'mask' (leaving * other ones that are currently enabled on). If the mask * includes bits that were not passed to the 'setup' routine * then the behavior is undefined. * RETURNS: Bitmask of interrupts that were enabled upon entry * into this routine. This can be used to restore the previous * state. */ uint32_t BSP_tsec_disable_irq_mask(struct tsec_private *mp, uint32_t irq_mask); /* Acknowledge and clear selected interrupts. * * RETURNS: All pending interrupts. * * NOTE: Only pending interrupts contained in 'mask' * are cleared. Others are left pending. * * This routine can be used to check for pending * interrupts (pass mask == 0) or to clear all * interrupts (pass mask == -1). */ uint32_t BSP_tsec_ack_irq_mask(struct tsec_private *mp, uint32_t mask); /* 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