tte_eth_driver.h File Reference

NIC driver interface to the TTE protocol layer. More...

#include "tte_environment.h"
#include "tte_common.h"
#include "tte_hw_timer.h"
#include "tte_api.h"

Go to the source code of this file.

Classes

struct  __attribute__
struct  __attribute__
struct  __attribute__
struct  eth_buffer_t
 Structure describing one Ethernet buffer. These buffers are passed between the NIC driver and the TTEthernet core. The core passes them in an encapulated form further to the applications. More...
struct  tte_eth_stats_t
struct  eth_intr_t

Defines

#define ETH_HEADER_LEN   (14u)

Typedefs

typedef int32_t(* eth_rx_callback_t )(uint8_t ctrl, hwtime_t ts)
typedef int32_t(* eth_error_callback_t )(uint8_t ctrl, int32_t error_code)

Enumerations

enum  eth_errror_code_t { ETH_ERR_LINK = 1, ETH_ERR_IRQ = 2, ETH_ERR_RXOVER = 3, ETH_ERR_OTHER = 99 }
enum  { ETH_LINK_UP, ETH_LINK_DOWN }

Functions

int32_t eth_alloc_rx_bufs (uint8_t ctrl, uint32_t count)
 Allocate reception buffers.
int32_t eth_alloc_tx_bufs (uint8_t ctrl, uint32_t count, uint16_t size)
 Allocate transmission buffers.
int32_t eth_clear_mc_list (uint8_t ctrl)
 Clear the MAC hash table in the NIC.
void eth_exit (void)
 Release all resources.
int32_t eth_flush_rx_queue (uint8_t ctrl)
 Clear the RX queue.
int32_t eth_flush_tx_queue (uint8_t ctrl)
 Clear the TX queue.
int32_t eth_free_buffers (uint8_t ctrl)
 free allocated buffers
int32_t eth_free_rx_buf (uint8_t ctrl, eth_buffer_t *buf)
 Free the RX buffer.
int32_t eth_get_card_count (void)
 Return the number of NICs available for TT Ethernet.
int32_t eth_get_stats (uint8_t ctrl, tte_eth_stats_t *stats)
 Read the statistics counters.
int32_t eth_get_link_status (uint8_t ctrl)
 Get the current link status.
int32_t eth_get_mac_addr (uint8_t ctrl, eth_mac_addr_t *addr)
 Read the MAC address.
int32_t eth_get_prom_mode (uint8_t ctrl)
 Read the promiscuous settings.
int32_t eth_get_rx_buf (uint8_t ctrl, eth_buffer_t *buf)
 Get the RX buffer.
int32_t eth_get_tx_buf (uint8_t ctrl, eth_buffer_t *buf, uint16_t size)
 Request a free TX buffer.
int32_t eth_init (void)
 Initialize the driver.
void eth_register_error_callback (uint8_t ctrl, eth_error_callback_t fn)
 Register an error callback.
void eth_register_rx_callback (uint8_t ctrl, eth_rx_callback_t fn)
 Register a RX callback.
void eth_set_int_mask (uint8_t ctrl, eth_intr_t int_mask)
 set the interrupt enable mask
int32_t eth_set_mac_addr (uint8_t ctrl, eth_mac_addr_t addr)
 Set the MAC address.
int32_t eth_set_mc_list (uint8_t ctrl, eth_mac_addr_t *mac_list, uint32_t len)
 Set a list of multicast addresses.
int32_t eth_set_multicast_addr (uint8_t ctrl, eth_mac_addr_t *mac_addr)
 Set a multicast address.
int32_t eth_set_prom_mode (uint8_t ctrl, int32_t promisc)
 Set the promiscuous mode.
int32_t eth_start (uint8_t ctrl)
 Start one TT Ethernet card.
int32_t eth_stop (uint8_t ctrl)
 Stop one TT Ethernet card.
int32_t eth_tx_buf (uint8_t ctrl, eth_buffer_t *buf)
 Transmit the TX buffer.
int32_t eth_free_tx_buf (uint8_t ctrl, eth_buffer_t *buf)
 Free the TX buffer (no transmit is requested).

Detailed Description

NIC driver interface to the TTE protocol layer.

Definition in file tte_eth_driver.h.


Define Documentation

#define ETH_HEADER_LEN   (14u)

Ethernet MAC header length in bytes

Definition at line 31 of file tte_eth_driver.h.


Typedef Documentation

typedef int32_t(* eth_error_callback_t)(uint8_t ctrl, int32_t error_code)

Prototype for an error callback. The error_code argumet is one of ETH_ERR_LINK, ETH_ERR_OTHER.

Definition at line 53 of file tte_eth_driver.h.

typedef int32_t(* eth_rx_callback_t)(uint8_t ctrl, hwtime_t ts)

Prototype for a receive callback.

Definition at line 34 of file tte_eth_driver.h.


Enumeration Type Documentation

anonymous enum

Status of the PHY link.

Enumerator:
ETH_LINK_UP 
ETH_LINK_DOWN 

Definition at line 57 of file tte_eth_driver.h.

00057      {
00058    ETH_LINK_UP,
00059    ETH_LINK_DOWN
00060 };

Ethernet error callback uses these values to give detailed information about the error.

Enumerator:
ETH_ERR_LINK 

PHY link was lost or obtained.

ETH_ERR_IRQ 

Error reported by card via an IRQ.

ETH_ERR_RXOVER 

RX buffer overflow in NIC.

ETH_ERR_OTHER 

Any other error.

Definition at line 43 of file tte_eth_driver.h.

00043              {
00044     ETH_ERR_LINK   = 1,     
00045     ETH_ERR_IRQ    = 2,     
00046     ETH_ERR_RXOVER = 3,     
00047     ETH_ERR_OTHER  = 99,    
00048 } eth_errror_code_t;


Function Documentation

int32_t eth_alloc_rx_bufs ( uint8_t  ctrl,
uint32_t  count 
)

Allocate reception buffers.

Allocate the given number of RX buffers. All RX buffers will be large enough to contain a maximum size Ethernet frame.

Parameters:
ctrl - Controller ID of the Ethernet device
count - Amount of buffers to be allocated and added
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_LINKLOST - if the link is up
  • ETT_NOMEM - if no memory is available (RX buffer descriptor or RX buffer structures)
int32_t eth_alloc_tx_bufs ( uint8_t  ctrl,
uint32_t  count,
uint16_t  size 
)

Allocate transmission buffers.

Allocate the given number of TX buffers with the specified minimum size in bytes. The driver may allocate larger buffers. Any previously allocated TX buffers are still valid.

Parameters:
ctrl - Controller ID of the Ethernet device
count - Amount of buffers to be allocated
size - The size of one buffer in bytes
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_LINKLOST - if the link is already up
  • ETT_NOMEM - if no memory is available (TX buffer descriptor or TX buffer structures)
int32_t eth_clear_mc_list ( uint8_t  ctrl  ) 

Clear the MAC hash table in the NIC.

The MAC hash table of the NIC is cleared.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
void eth_exit ( void   ) 

Release all resources.

This function releases all resources. The call to this function shall never fail.

int32_t eth_flush_rx_queue ( uint8_t  ctrl  ) 

Clear the RX queue.

This function drops all received buffers. Receptions in progress will not be stopped.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
int32_t eth_flush_tx_queue ( uint8_t  ctrl  ) 

Clear the TX queue.

This function drops all buffers from the transmit queue. Transmissions in progress will not be stopped.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
int32_t eth_free_buffers ( uint8_t  ctrl  ) 

free allocated buffers

Free alloated buffer descriptors, linked buffers, free buffers and Ethernet buffers.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
int32_t eth_free_rx_buf ( uint8_t  ctrl,
eth_buffer_t buf 
)

Free the RX buffer.

Free the allocated RX buffer back to the NIC driver. The buffer must no longer be accessed by the caller.

Parameters:
ctrl - Controller ID of the Ethernet device
buf - Pointer to the Ethernet buffer that should be freed
Returns:
int32_t eth_free_tx_buf ( uint8_t  ctrl,
eth_buffer_t buf 
)

Free the TX buffer (no transmit is requested).

This function frees the buffer without transmission.

Parameters:
ctrl - Controller ID of the Ethernet device
buf - Pointer to the Ethernet buffer that shall be freed.
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the TX buffer is NULL
int32_t eth_get_card_count ( void   ) 

Return the number of NICs available for TT Ethernet.

Returns:
  • a positive or zero return value is the amount of NICs available for TT Ethernet
  • a negative error code in case the operation fails.
int32_t eth_get_link_status ( uint8_t  ctrl  ) 

Get the current link status.

This function returns the current link status

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
int32_t eth_get_mac_addr ( uint8_t  ctrl,
eth_mac_addr_t *  addr 
)

Read the MAC address.

Store the MAC address configured in the NIC into the passed addr structure.

Parameters:
ctrl - Controller ID of the Ethernet device
addr - A pointer to a structure where the MAC address shall be stored.
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the MAC address structure is NULL
int32_t eth_get_prom_mode ( uint8_t  ctrl  ) 

Read the promiscuous settings.

Return the current settings of the promiscuous mode:

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
  • 0 - if promiscuous mode is disabled
  • 1 - if promiscuous mode is enabled
  • ETT_INVCTRL - if an invalid controller ID was passed
int32_t eth_get_rx_buf ( uint8_t  ctrl,
eth_buffer_t buf 
)

Get the RX buffer.

This function copies the oldest received frame into the passed buffer and returns the size of the received data in bytes (including the Ethernet header but without the FCS).

Parameters:
ctrl - Controller ID of the Ethernet device
buf - Pointer to the Ethernet buffer where the received frame shall be stored
Returns:
  • a positive value holds the length of the RX buffer
  • ETT_SUCCESS - if no frame was received
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the TX buffer is NULL
  • ETT_NOSPC - if the receive queue is full
int32_t eth_get_stats ( uint8_t  ctrl,
tte_eth_stats_t stats 
)

Read the statistics counters.

Read the statistics counters from the NIC and store them in the provided structure.

Parameters:
ctrl - Controller ID of the Ethernet device
stats - Pointer to the counter structure where the counter values are copied
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the counter structure is NULL
int32_t eth_get_tx_buf ( uint8_t  ctrl,
eth_buffer_t buf,
uint16_t  size 
)

Request a free TX buffer.

This function requests a free TX buffer by passing a buffer and the minimum requested size. The caller stores the complete Ethernet frame in the buffer (including the Ethernet header but without the FCS).

Parameters:
ctrl - Controller ID of the Ethernet device
buf - Pointer to an Ethernet buffer where the empty buffer is copied.
size - The minimum size of the buffer in bytes
Returns:
  • a positive value holds the length of the free TX buffer
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NOMEM - The requested size is too large or the buffer descriptor is not marked as empty
  • ETT_NULLPTR - The passed pointer to the TX buffer is NULL
  • ETT_NOSPC - The TX queue is full
int32_t eth_init ( void   ) 

Initialize the driver.

This function initializes the Ethernet driver.

Returns:
void eth_register_error_callback ( uint8_t  ctrl,
eth_error_callback_t  fn 
)

Register an error callback.

Register a function that will be called when an error occurs. The interrupts in the NIC are by default disabled and must be enabled via eth_set_int_mask. If there was an older registered callback, it will be replaced. Specifying NULL as the callback function address will clear the callback registration.

Note: The driver must acknowledge the interrupt.

Parameters:
ctrl - Controller ID of the Ethernet device
fn - The error callback function that shall be registered.
void eth_register_rx_callback ( uint8_t  ctrl,
eth_rx_callback_t  fn 
)

Register a RX callback.

Register a function that is called when a message is fully received by the NIC (available for pickup via eth_get_rx_buf). The RX interrupts are disabled by default and must be enabled via eth_set_int_mask. If there was an older registered callback, it will be replaced. Specifying NULL as the callback function address will clear the registered callback.

Note: The RX queue of the NIC may already contain buffers and the callback function will not be called for these. The user has to read these out explicitly by repeated calling of eth_get_rx_buf or flush them via eth_flush_rx_queue.

Note: The driver must acknowledge the interrupt.

Parameters:
ctrl - Controller ID of the Ethernet device
fn - The RX callback function that shall be registered.
void eth_set_int_mask ( uint8_t  ctrl,
eth_intr_t  int_mask 
)

set the interrupt enable mask

Change the interrupt-enable mask in the NIC.

Parameters:
ctrl - Controller ID of the Ethernet device
int_mask - A structure containing the error and the RX interrupt mask
int32_t eth_set_mac_addr ( uint8_t  ctrl,
eth_mac_addr_t  addr 
)

Set the MAC address.

Change the NIC's MAC address.

Parameters:
ctrl - Controller ID of the Ethernet device
addr - The MAC address that shall be used for transmitting Ethernet frames
Returns:
int32_t eth_set_mc_list ( uint8_t  ctrl,
eth_mac_addr_t *  mac_list,
uint32_t  len 
)

Set a list of multicast addresses.

Set the list of accepted multicast addresses in the NIC.

Note, that the filtering might be based on a hash table and the NIC will accept some frames with MAC addresses that are not in the supplied list.

Parameters:
ctrl - Controller ID of the Ethernet device
mac_list - The list of MAC address that shall be accepted
len - The amount of entries in mac_list
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the list of MAC addresses is NULL
  • ETT_FAILED - if setting the list of MAC addresses fails
int32_t eth_set_multicast_addr ( uint8_t  ctrl,
eth_mac_addr_t *  mac_addr 
)

Set a multicast address.

Set MAC address in the list of accepted multicast addresses in the NIC.

Parameters:
ctrl - Controller ID of the Ethernet device
mac_addr - Pointer to the MAC address to be added to the list of accepted multicast addresses
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_NULLPTR - if the passed pointer to the list of MAC addresses is NULL
  • ETT_FAILED - if setting the list of MAC addresses fails
int32_t eth_set_prom_mode ( uint8_t  ctrl,
int32_t  promisc 
)

Set the promiscuous mode.

Change the way the NIC will decide what incoming frames to accept. When promisc is 0, only the frames with matching destination address, broadcast frames or frames with a multicast address that passes the hash-table match are accepted. When promisc is not 0, all frames are accepted. The initial mode is not promiscuous.

Parameters:
ctrl - Controller ID of the Ethernet device
promisc - Promiscuous mode is disabled if promisc is 0. Otherwise the promiscuous mode is enabled
Returns:
int32_t eth_start ( uint8_t  ctrl  ) 

Start one TT Ethernet card.

Initialize the card with the given number (range 0..num_of_cards-1). Establish a link, read the MAC address from EEPROM and set it in the NIC. RX and TX buffers must be allocated via eth_alloc_tx_bufs, and eth_alloc_rx_bufs before starting the NIC.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
int32_t eth_stop ( uint8_t  ctrl  ) 

Stop one TT Ethernet card.

Shut down the card, free all allocated resources. The function call never fails.

Parameters:
ctrl - Controller ID of the Ethernet device
Returns:
  • ETT_SUCCESS - in case the operation was successful
  • ETT_INVCTRL - if an invalid controller ID was passed
  • ETT_INVDRVSTAT - if the driver is uninitialized or started
int32_t eth_tx_buf ( uint8_t  ctrl,
eth_buffer_t buf 
)

Transmit the TX buffer.

This function transmits the passed buffer over Ethernet. The size is specified in bytes and includes the Ethernet header.

Parameters:
ctrl - Controller ID of the Ethernet device
buf - Pointer to the Ethernet buffer that shall be transmitted.
Returns:
Generated on Tue Nov 29 14:09:19 2011 for TTEthernet Model for INET Framework by  doxygen 1.6.3