LXR 6.1/​bsps/​powerpc/​mvme3100/​include/​bsp/​if_tsec_pub.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:23:56

 /**
  *  @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 <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>
 #include <stdint.h>
 
 #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

This page was automatically generated by the 2.3.7 LXR engine. The LXR team