path: root/c/src/lib/libbsp/powerpc/mvme3100/network/if_tsec_pub.h

#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