Ethernet API

Configuration Defines

The file ethernet_conf.h may be provided in the application source code. This file can set the following defines:

ETHERNET_DEFAULT_IMPLEMENTATION

This define can be set to full or lite and determines which implementation is chosen by default when the application makes calls to ethernet_server etc.

Configuration Defines for FULL implementation

MAX_ETHERNET_PACKET_SIZE

This define sets the largest packet size in bytes that the ethernet mac will receive. The default is the largest possible ethernet packet size (1518 bytes). Setting this to a smaller value will save memory but restrict the type of packets you can receieve.

NUM_MII_RX_BUF

Number of incoming packets that will be buffered within the MAC.

NUM_MII_TX_BUF

Number of outgoing packets that will be buffered within the MAC.

MAX_ETHERNET_CLIENTS

The maximum number of clients that can be connected to the ethernet_server() function via the rx and tx channel arrays.

NUM_ETHERNET_PORTS

The number of ethernet ports to support. Maximum value is 2 in the current implementation.

ETHERNET_TX_HP_QUEUE

Define this constant to include the high priority transmit queueing mechanism. This enables frames which have an ethernet VLAN priority tag to be queued in a high priority queue, which in turn can be managed with the 802.1qav transmit traffic shaper.

ETHERNET_RX_HP_QUEUE

Define this constant to include high priority reception of ethernet VLAN priority tagged traffic. This traffic will be queued into a fast queue and delivered to the clients ahead of non-tagged traffic.

ETHERNET_TRAFFIC_SHAPER

If high priority transmit queueing is in use (see ETHERNET_TX_HP_QUEUE) then this enables the 802.1qav traffic shaping algorithm.

MII_RX_BUFSIZE_HIGH_PRIORITY

The number of quadlets (4 byte integers) of space in the high priority receive buffer. The buffer will actually be two full packets longer than this to avoid the need to be circular. This constant applies when the high priority receive queue is in use.

MII_RX_BUFSIZE_LOW_PRIORITY

The number of quadlets (4 byte integers) of space in the low priority receive buffer. The buffer will actually be two full packets longer than this to avoid the need to be circular. This constant applies when the high priority receive is in use.

MII_RX_BUFSIZE

The number of quadlets (4 byte integers) of space in the low priority receive buffer. The buffer will actually be two full packets longer than this to avoid the need to be circular. This constant applies when the high priority receive is not in use.

MII_TX_BUFSIZE

The number of quadlets (4 byte integers) of space in the low priority transmit buffer. The buffer will actually be two full packets longer than this to avoid the need to be circular.

MII_TX_BUFSIZE_HIGH_PRIORITY

The number of quadlets (4 byte integers) of space in the high priority transmit buffer. The buffer will actually be two full packets longer than this to avoid the need to be circular. This constant applies when the high priority receive is in use.

ENABLE_ETHERNET_SOURCE_ADDRESS_WRITE

By defining this preprocessor symbol, the source MAC address will be automatically filled in with the MAC address passed to the port during initialization.

Configuration defines for LITE implementation

Custom Filter Function

For the FULL implementation, every application is required to provide this function. It also needs to be prototyped (or defined as an inline definition) in the header file mac_custom_filter.h.

  • int mac_custom_filter(unsigned int data[])

    This function examines an ethernet packet and returns a filter number to allow different clients to obtain different types of packet. The function must run within 6us to allow 100Mbit filtering of packets.

    Parameters

    • data

      This array contains the ethernet packet. It does not include the preamble but does include the layer 2 header or the packet.

    Returns

    0 if the packet is not wanted by the application or a number that can be registed by mac_set_custom_filter() by a client. Clients register a mask so the number is usually made up of a bit per unique client destination for the packet.

Data Structures

Depending on the implementation you must supply a different port structure. The type mii_interface_t will be set to one of this structures depending on the ETHERNET_DEFAULT_IMPLEMENTATION define.

  • mii_interface_full_t

    Structure containing resources required for the MII ethernet interface.

    This structure contains resources required to make up an MII interface. It consists of 7 ports and 2 clock blocks.

    The clock blocks can be any available clock blocks and will be clocked of incoming rx/tx clock pins.

    Structure Members:

    • clock clk_mii_rx

      MII RX Clock Block.

    • clock clk_mii_tx

      MII TX Clock Block.

    • in port p_mii_rxclk

      MII RX clock wire.

    • in port p_mii_rxer

      MII RX error wire.

    • in buffered port:32 p_mii_rxd

      MII RX data wire.

    • in port p_mii_rxdv

      MII RX data valid wire.

    • in port p_mii_txclk

      MII TX clock wire.

    • out port p_mii_txen

      MII TX enable wire.

    • out buffered port:32 p_mii_txd

      MII TX data wire.

  • mii_interface_lite_t

    Structure Members:

    • clock clk_mii_rx

      MII RX Clock Block.

    • clock clk_mii_tx

      MII TX Clock Block.

    • in port p_mii_rxclk

      MII RX clock wire.

    • in port p_mii_rxer

      MII RX error wire.

    • in buffered port:32 p_mii_rxd

      MII RX data wire.

    • in port p_mii_rxdv

      MII RX data valid wire.

    • in port p_mii_txclk

      MII TX clock wire.

    • out port p_mii_txen

      MII TX enable wire.

    • out buffered port:32 p_mii_txd

      MII TX data wire.

    • in port p_mii_timing

      A port that is not used for anything, used by the LLD for timing purposes.

      Must be clocked of the reference clock

MAC Server API

  • void ethernet_server(mii_interface_t &mii, smi_interface_t & ?smi, char mac_address[], chanend rx[], int num_rx, chanend tx[], int num_tx)

    Single MII port MAC/ethernet server.

    This function provides both MII layer and MAC layer functionality. It runs in 5 threads and communicates to clients over the channel array parameters.

    The clients connected via the rx/tx channels can communicate with the server using the APIs found in ethernet_rx_client.h and ethernet_tx_client.h

    Parameters

    • mii

      The mii interface resources that the server will connect to

    • mac_address

      The mac_address the server will use. This should be a two-word array that stores the 6-byte macaddr in a little endian manner (so reinterpreting the array as a char array is as one would expect)

    • rx

      An array of chanends to connect to clients of the server who wish to receive packets.

    • num_rx

      The number of clients connected to the rx array

    • tx

      An array of chanends to connect to clients of the server who wish to transmit packets.

    • num_tx

      The number of clients connected to the txx array

    • smi

      An optional parameter of resources to connect to a PHY (via SMI) to check when the link is up.

RX Client API

Packet Receive Functions

  • void mac_rx(chanend c_mac, unsigned char buffer[], unsigned int &len, unsigned int &src_port)

    This function receives a complete frame (i.e.

    src/dest MAC address, type & payload), excluding pre-amble, SoF & CRC32 from the ethernet server.

    This function is selectable i.e. it can be used as a case in a select e.g.

    select {
   ...
   case mac_rx(...):
      break;
    ...
  }

    Parameters

    • c_mac

      A chanend connected to the ethernet server

    • buffer

      The buffer to fill with the incoming packet

    • src_port

      A reference parameter to be filled with the ethernet port the packet came from.

    • len

      A reference parameter to be filled with the length of the received packet in bytes.

  • void mac_rx_timed(chanend c_mac, unsigned char buffer[], unsigned int &len, unsigned int &time, unsigned int &src_port)

    This function receives a complete frame (i.e.

    src/dest MAC address, type & payload), excluding pre-amble, SoF & CRC32. It also timestamps the arrival of the frame.

    This function is selectable.

    Parameters

    • c_mac

      A chanend connected to the ethernet server

    • buffer

      The buffer to fill with the incoming packet

    • time

      A reference parameter to be filled with the timestamp of the packet

    • len

      A reference parameter to be filled with the length of the received packet in bytes.

    • src_port

      A reference parameter to be filled with the ethernet port the packet came from.

  • void safe_mac_rx(chanend c_mac, unsigned char buffer[], unsigned int &len, unsigned int &src_port, int n)

    This function receives a complete frame (i.e.

    src/dest MAC address, type & payload), excluding pre-amble, SoF & CRC32. In addition it will only fill the given buffer up to a specified length.

    This function is selectable.

    Parameters

    • c_mac

      A chanend connected to the ethernet server

    • buffer

      The buffer to fill with the incoming packet

    • len

      A reference parameter to be filled with the length of the received packet in bytes.

    • src_port

      A reference parameter to be filled with the ethernet port the packet came from.

    • n

      The maximum number of bytes to fill the supplied buffer with.

  • void safe_mac_rx_timed(chanend c_mac, unsigned char buffer[], unsigned int &len, unsigned int &time, unsigned int &src_port, int n)

    This function receives a complete frame (i.e.

    src/dest MAC address, type & payload), excluding pre-amble, SoF & CRC32 from the ethernet server. In addition it will only fill the given buffer up to a specified length.

    This function is selectable i.e. it can be used as a case in a select.

    Parameters

    • c_mac

      A chanend connected to the ethernet server

    • buffer

      The buffer to fill with the incoming packet

    • src_port

      A reference parameter to be filled with the ethernet port the packet came from.

    • len

      A reference parameter to be filled with the length of the received packet in bytes.

    • n

      The maximum number of bytes to fill the supplied buffer with.

  • void mac_rx_offset2(chanend c_mac, unsigned char buffer[], unsigned int &len, unsigned int &src_port)

    Receive a packet starting at the second byte of a buffer.

    This is useful when the contents of the packet should be aligned on a different boundary.

    Parameters

    • c_mac

      chanend of receive server.

    • buffer

      The buffer to fill with the incoming packet

    • len

      A reference parameter to be filled with the length of the received packet in bytes.

    • src_port

      A reference parameter to be filled with the ethernet port the packet came from.

Configuration Functions

  • void mac_set_drop_packets(chanend c_mac_svr, int x)

    Setup whether a link should drop packets or block if the link is not ready.

    NOTE: setting no dropped packets does not mean no packets will be dropped. If packets are not dropped at the mac layer, it will block the mii fifo. The Mii fifo could possibly overflow and frames for other links could be dropped.

    Parameters

    • c_mac_svr

      chanend of receive server.

    • x

      boolean value as to whether packets should be dropped at mac layer.

  • void mac_set_queue_size(chanend c_mac_svr, int x)

    Setup the size of the buffer queue within the mac attached to this link.

    Parameters

    • c_mac_svr

      chanend connected to the mac

    • x

      the required size of the queue

  • void mac_set_custom_filter(chanend c_mac_svr, int x)

    Setup the custom filter up on a link.

    For each packet, the filter value is &-ed against the result of the mac_custom_filter function. If the result is non-zero then the packet is transmitted down the link.

    Parameters

    • c_mac_svr

      chanend of receive server.

    • x

      filter value

TX Client API

Packet Transmit Functions

  • void mac_tx(chanend c_mac, unsigned int buffer[], int nbytes, int ifnum)

    Sends an ethernet frame.

    Frame includes dest/src MAC address(s), type and payload.

    Parameters

    • c_mac

      channel end to tx server.

    • buffer[]

      byte array containing the ethernet frame. This must be word aligned

    • nbytes

      number of bytes in buffer

    • ifnum

      the number of the eth interface to transmit to (use ETH_BROADCAST transmits to all ports)

  • void mac_tx_timed(chanend c_mac, unsigned int buffer[], int nbytes, unsigned int &time, int ifnum)

    Sends an ethernet frame and gets the timestamp of the send.

    Frame includes dest/src MAC address(s), type and payload.

    This is a blocking call and returns the actual time the frame is sent to PHY according to the XCore 100Mhz 32-bit timer on the core the ethernet server is running.

    NOTE: This function will block until the packet is sent to PHY.

    Parameters

    • c_mac

      channel end connected to ethernet server.

    • buffer[]

      byte array containing the ethernet frame. This must be word aligned

    • nbytes

      number of bytes in buffer

    • ifnum

      the number of the eth interface to transmit to (use ETH_BROADCAST transmits to all ports)

    • time

      A reference paramater that is set to the time the packet is sent to the phy

  • void mac_tx_offset2(chanend c_mac, unsigned int buffer[], int nbytes, int ifnum)

    Sends an ethernet frame.

    Frame includes dest/src MAC address(s), type and payload.

    The packet should start at offset 2 in the buffer. This allows the packet to be constructed with alignment on a different boundary, allowing for more efficient construction where many word values are not naturally aligned on word boundaries.

    Parameters

    • c_mac

      channel end to tx server.

    • buffer[]

      byte array containing the ethernet frame. This must be word aligned

    • nbytes

      number of bytes in buffer

    • ifnum

      the number of the eth interface to transmit to (use ETH_BROADCAST transmits to all ports)

Ethernet function synonyms

Synonym

Function

ethernet_send_frame

ethernet_send_frame

ethernet_send_frame_getTime

ethernet_send_frame_getTime

ethernet_send_frame_offset2

mac_tx_offset2

ethernet_get_my_mac_adrs

mac_get_macaddr

Configuration Functions

  • int mac_get_macaddr(chanend c_mac, unsigned char macaddr[])

    Get the device MAC address.

    This function gets the MAC address of the device (the address passed into the ethernet_server() function.

    Parameters

    • c_mac

      chanend end connected to ethernet server

    • macaddr[]

      an array of type char where the MAC address is placed (in network order).

    Returns

    zero on success and non-zero on failure.

See Also