<< >>

Ethernet API

Configuration Defines

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

MAX_ETHERNET_PACKET_SIZE

This define sets the largest packet size in bytes that the ethernet mac will receive. The default it 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.

DISABLE_ETHERNET_PORT_FORWARDING

By defining this preprocessor symbol, the forwarding of packets between ports, when there are multiple ports, is disabled. Traffic is only forwarded to the clients.

Custom Filter Function

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

mii_interface_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.

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

smi_interface_t

Structure containing resources required for the SMI ethernet phy interface.

This structure contains the resources required to communicate with an ethernet phy over smi.

Structure Members:

port p_smi_mdio

MDIO port.

out port p_smi_mdc

MDC port.

int mdio_mux

This flag needs to be set if the MDIO port is shared with the phy reset line.

OTP MAC Address Reading

void ethernet_getmac_otp(port otp_data, out port otp_addr, port otp_ctrl, char macaddr[])

Retrieves the first MAC address stored in the OTP.

Parameters:
  • otp_data – Data port connected to otp
  • otp_addr – Address port connected to otp
  • otp_ctrl – Control port connected to otp
  • macaddr – Array to be filled with the retrieved MAC address
void ethernet_getmac_otp_indexed(port otp_data, out port otp_addr, port otp_ctrl, int macaddr[], unsigned index)

Retrieves the requested indexed MAC address stored in the OTP.

Parameters:
  • otp_data – Data port connected to otp
  • otp_addr – Address port connected to otp
  • otp_ctrl – Control port connected to otp
  • macaddr – Array to be filled with the retrieved MAC address
  • index – The index of the mac address to retreive
void ethernet_getmac_otp_count(port otp_data, out port otp_addr, port otp_ctrl, int macaddr[][2], unsigned count)

Retrieves a set of MAC addresses stored in the OTP.

Parameters:
  • otp_data – Data port connected to otp
  • otp_addr – Address port connected to otp
  • otp_ctrl – Control port connected to otp
  • macaddr – Array to be filled with the retrieved MAC address
  • count – The number of the mac address to retreive

Ethernet Phy API

void phy_init(clock clk_smi, out port ?p_mii_resetn, smi_interface_t &smi0, mii_interface_t &mii0)

Reset and initialize the ethernet phy.

This function resets the ethernet phy and initializes the MII resources. It should be called before calling ethernet_server(). This function is designed to work with SMSC phys

Parameters:
  • clk_smi – The clock block used for smi clocking
  • p_mii_resetn – This port connected to the phy reset line. This parameter can be null if the reset line is multiplexed on the SMI MDIO port.
  • smi0 – The SMI resources to connect to the phy
  • mii0 – The MII resources to connect to the phy
void phy_init_two_port(clock clk_smi, out port ?p_mii_resetn, smi_interface_t &smi0, smi_interface_t &smi1, mii_interface_t &mii0, mii_interface_t &mii1)

Reset and initialize two ethernet phys.

This function resets the ethernet phys and initializes the MII resources. It should be called before calling ethernet_server_two_port(). This function is designed to work with SMSC phys

Parameters:
  • clk_smi – The clock block used for smi clocking
  • p_mii_resetn – This port connected to the phy reset line. This parameter can be null if the reset line is multiplexed on the SMI MDIO port.
  • smi0 – The first SMI resources to connect to the phy
  • smi1 – The second SMI resources to connect to the phy
  • mii0 – The first MII resources to connect to the phy
  • mii1 – The second MII resources to connect to the phy

MAC Server API

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

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.
  • connect_status – An optional parameter of a channel that is signalled when the link goes up or down (requires the smi parameter to be supplied).

If the smi and connect_status parameters are supplied then the connect_status channel will output when the link goes up or down. The channel will output a zero byte, followed by the status (1 for up, 0 for down), followed by a zero byte, followed by an END control token.,

The following code snippet is an example of how to receive this update:

(void) inuchar(connect_status);
new_status = inuchar(c);
(void) inuchar(c, 0);
(void) inct(c);
void ethernet_server_two_port(mii_interface_t &mii1, mii_interface_t &mii2, int mac_address[], chanend rx[], int num_rx, chanend tx[], int num_tx, smi_interface_t & ?smi1, smi_interface_t & ?smi2, chanend ?connect_status)

Dual MII port MAC/ethernet server.

This function provides both MII layer and MAC layer functionality. It runs in 7 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:
  • mii1 – The first mii interface resources that the server will connect to
  • mii2 – The second 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
  • smi1 – An optional parameter of resources to connect to the first PHY (via SMI) to check when the link is up.
  • smi2 – An optional parameter of resources to connect to a second PHY (via SMI) to check when the link is up.
  • connect_status – An optional parameter of a channel that is signalled when the link goes up or down (requires the smi parameter to be supplied).

If the smi and connect_status parameters are supplied then the connect_status channel will output when the link goes up or down. The channel will output a zero byte, followed by the status (1 for up, 0 for down), followed by a zero byte, followed by an END control token.,

The following code snippet is an example of how to receive this update:

(void) inuchar(connect_status);
new_status = inuchar(c);
(void) inuchar(c, 0);
(void) inct(c);

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 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 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. It also timestamp the arrival of the frame. 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
  • 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.
  • 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.

Ethernet Component (1v4)