Ethernet (Ethernet interface)

General Description

High level interface for interacting with the Ethernet.

This driver supports initializing and configuring Infineon Ethernet MAC along with third party Ethernet PHY. The driver implements the functions for transmitting and receiveing Ethernet frames over the LAN network.

Note

Certain platforms may not support all of the Ethernet MAC to PHY interface mode MII, RMII, GMII and RGMII. Please refer to implementation specific documentation for details on available options.

Features

• Ethernet initialization
• Send and receive ethernet packets
• Ethernet flow control
• MAC filters
• Ethernet PHY low-level register control
• Configurable interrupt and callback assignment from ethernet events - cyhal_ethernet_event_t

Code Snippets

Snippet 1: Transmit Frame

The following snippet transmits an ethernet frame

 
static void ethernet_event_handler_transmit_frame(void* arg, cyhal_ethernet_event_t event)
{
    // When we registered the callback, we set 'arg' to point to the ethernet object
    cyhal_ethernet_t* ethernet_obj = (cyhal_ethernet_t*)arg;
    if (0u != (event & CYHAL_ETHERNET_TX_COMPLETE_EVENT))
    {
        //handle transmit error ex - request for re-transmit
        (void)ethernet_obj;
    }
}
 
 
void ethernet_transmit_frame(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    //* configure ethernet */
    const cyhal_ethernet_config_t eth_config =
    {
        .drive_mode   = CYHAL_ETHERNET_RMII_100,
        .clk_source   = CYHAL_ETHERNET_CLK_EXT,
        .ext_clk_freq = 25000000,
    };
 
    /* Setup ethernet pins for RMII mode */
    const cyhal_ethernet_pins_t ethernet_pins =
    {
        .eth_type_rmii.mdc       = ETH_MDC,
        .eth_type_rmii.mdio      = ETH_MDIO,
        .eth_type_rmii.ref_clk   = ETH_REF_CLK,
        .eth_type_rmii.tx_d0     = ETH_TXD0,
        .eth_type_rmii.tx_d1     = ETH_TXD1,
        .eth_type_rmii.tx_en     = ETH_TX_EN,
        .eth_type_rmii.rx_d0     = ETH_RXD0,
        .eth_type_rmii.rx_d1     = ETH_RXD1,
        .eth_type_rmii.rx_dv_crs = ETH_RX_DV_CRS,
        .eth_type_rmii.rx_err    = ETH_RX_ERR,
    };
 
    result = cyhal_ethernet_init(&ethernet_obj, &eth_config, &ethernet_pins, NULL);
 
    /* Register a callback and set the callback argument to be a pointer to the ethernet object, so
       that we can easily reference it from the callback handler. */
    cyhal_ethernet_register_callback(&ethernet_obj, &ethernet_event_handler_transmit_frame,
                                     &ethernet_obj);
 
    /* Subscribe to the transmit complete */
    cyhal_ethernet_enable_event(&ethernet_obj, CYHAL_ETHERNET_TX_COMPLETE_EVENT,
                                CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    uint8_t frame_data[1536] =
    {
        0
    };
 
    /* Load Destination MAC address    */
 
    frame_data[0] = 0xFF;
    frame_data[1] = 0xFF;
    frame_data[2] = 0xFF;
    frame_data[3] = 0xFF;
    frame_data[4] = 0xFF;
    frame_data[5] = 0xFF;
 
    /* Load source MAC address  */
    frame_data[6] = 0x02;
    frame_data[7] = 0x00;
    frame_data[8] = 0x00;
    frame_data[9] = 0x00;
    frame_data[10] = 0x00;
    frame_data[11] = 0x02;
 
    /* Load Ethertype  */
    frame_data[12] = 0x00;
    frame_data[13] = 0x00;
 
    /* Load Dummy payload  */
    for (uint16_t i = 0; i < 1500; i++)
    {
        frame_data[i + 14] = (uint8_t)i;
    }
 
    result =
        cyhal_ethernet_transmit_frame(&ethernet_obj, frame_data,
                                      sizeof(frame_data)/sizeof(frame_data[0]));
 
    (void)result;
}
 
 

Snippet 2: Receive Frame

The following snippet receives an ethernet frame

uint8_t frame_data[1536] =
{
    0
};
 
static void ethernet_event_handler_receive_frame(void* arg, cyhal_ethernet_event_t event)
{
    /* When we registered the callback, we set 'arg' to point to the ethernet object */
    cyhal_ethernet_t* ethernet_obj = (cyhal_ethernet_t*)arg;
    if (0u != (event & CYHAL_ETHERNET_RX_FRAME_EVENT))
    {
        /* Read ethernet frame */
        uint16_t frame_size = sizeof(frame_data) / sizeof(frame_data[0]);
        cy_rslt_t result = cyhal_ethernet_read_frame(ethernet_obj, frame_data, &frame_size);
 
        if (CY_RSLT_SUCCESS != result)
        {
            //handle copy error
        }
        else
        {
            /* frame_size now contains the amount of data that was read */
            (void)frame_size;
        }
    }
}
 
 
void snippet_cyhal_ethernet_receive_frame(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Register a callback and set the callback argument to be a pointer to the ethernet object, so
       that
       we can easily reference it from the callback handler.*/
    cyhal_ethernet_register_callback(&ethernet_obj, &ethernet_event_handler_receive_frame,
                                     &ethernet_obj);
 
    /* Subscribe to the receive notification */
    cyhal_ethernet_enable_event(&ethernet_obj, CYHAL_ETHERNET_RX_FRAME_EVENT,
                                CYHAL_ISR_PRIORITY_DEFAULT, true);
 
    (void)result;
}
 
 

Snippet 3: Flow control

The following snippet demonstrates using pause frames for flow control

 
void snippet_cyhal_ethernet_flow_control(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Define pause quanta, in this example, a value of 1 configure the MAC to send pause frames for
       512bit time duration.*/
    const uint16_t pause_quanta = 1;
 
    cy_rslt_t result = cyhal_ethernet_config_pause(&ethernet_obj, pause_quanta);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    /* Instruct MAC to begin transmitting pause frames. */
    bool start_pause = true;
    result = cyhal_ethernet_transmit_pause_frame(&ethernet_obj, start_pause);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle  error
    }
 
    /* Due to MAC sending pause frames, system not see any interrption from ethernet related,
       receiving the frame data */
 
    /* When ready to process Ethernet data stop sending pause frames.*/
    start_pause = false;
    result = cyhal_ethernet_transmit_pause_frame(&ethernet_obj, start_pause);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle  error
    }
 
    (void)result;
}
 
 

Snippet 4: MAC filtering

The following snippet demonstrates filtering packets by MAC address

 
void snippet_cyhal_ethernet_mac_filter(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Find number of the filters available in the MAC */
    uint8_t num_filters;
    num_filters = cyhal_ethernet_get_num_filter(&ethernet_obj);
 
    /* Configure first filter */
    uint8_t filter_num = 0;
 
    /* handle  error */
    if (filter_num >= num_filters)
    {
        //handle error
    }
 
    /* Set filter configuration to filter frames matching to source address. */
    cyhal_ethernet_filter_config_t config =
    {
        .filter_type = CYHAL_ETHERNET_FILTER_TYPE_SOURCE,
        .mac_addr[0] = 0x02,
        .mac_addr[1] = 0x00,
        .mac_addr[2] = 0x00,
        .mac_addr[3] = 0x00,
        .mac_addr[4] = 0x00,
        .mac_addr[5] = 0x02,
        .ignore_bytes= 0,
    };
 
    /* set first MAC filter */
    result = cyhal_ethernet_set_filter_address(&ethernet_obj, filter_num, &config);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    /* disable copy all frames */
    result = cyhal_ethernet_set_promiscuous_mode(&ethernet_obj, false);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    /* (Optional) If required disable receiving broad cast message also */
    result = cyhal_ethernet_enable_broadcast_receive(&ethernet_obj, false);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    (void)result;
}
 
 

Snippet 5: 1588 timer set

The following snippet demonstrates setting the 1588 timer value

 
void snippet_cyhal_ethernet_set_1588_timer_value(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Set the start value of timer as default 0 */
    cyhal_ethernet_1588_timer_val_t timer_val =
    {
        .secs_upper = 0,
        .secs_lower = 0,
        .nano_secs  = 0,
    };
 
    /* set 1588 timer value */
    result = cyhal_ethernet_set_1588_timer_value(&ethernet_obj, &timer_val);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
 
    (void)result;
}
 
 

Snippet 6: 1588 timer get

The following snippet demonstrates getting the 1588 timer value

 
void snippet_cyhal_ethernet_get_1588_timer_value(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
    cyhal_ethernet_1588_timer_val_t timer_val;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* set 1588 timer value */
    result = cyhal_ethernet_get_1588_timer_value(&ethernet_obj, &timer_val);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    (void)result;
}
 
 

Snippet 7: PHY Register Write

The following snippet demonstrates writing a low-level PHY register

 
void snippet_cyhal_ethernet_phy_write(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Basic control register 0x0000 as per IEEE 802.3 Ethernet PHY register map. */
    uint32_t reg_address = 0x00;
 
    /* Set BIT15 in the register to reset PHY */
    uint32_t reg_data = 0x8000;
 
    /* Write into PHY */
    result = cyhal_ethernet_phy_reg_write(&ethernet_obj, reg_address, reg_data);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    (void)result;
}
 
 

Snippet 8: PHY Register Read

The following snippet demonstrates reading a low-level PHY register

 
void snippet_cyhal_ethernet_phy_read(void)
{
    /* General: error handling is not shown. Use CY_ASSERT(CY_RSLT_SUCCESS == result); to check */
 
    /* variable declaration */
    cy_rslt_t result;
    cyhal_ethernet_t ethernet_obj;
 
    /* Initialize ethernet object as shown in snippet 1 */
 
    /* Basic control register 0x0000 as per IEEE 802.3 Ethernet PHY register map. */
    uint32_t reg_address = 0x00;
 
    /* Read register data */
    uint32_t reg_data;
 
    /* Read from PHY */
    result = cyhal_ethernet_phy_reg_read(&ethernet_obj, reg_address, &reg_data);
    if (CY_RSLT_SUCCESS != result)
    {
        //handle error
    }
 
    (void)result;
}
 
 

API Reference
	Ethernet HAL Results
	Ethernet specific return codes.
	Group_hal_ethernet_header
	Some Ethernet Header types (see IEEE 802.3 for full list)

Data Structures
struct	cyhal_ethernet_mii_pins_t
	Pins to use for MAC to PHY interface for MII drive mode. More...
struct	cyhal_ethernet_rmii_pins_t
	Pins to use for MAC to PHY interface for RMII drive mode. More...
struct	cyhal_ethernet_gmii_pins_t
	Pins to use for MAC to PHY interface for GMII drive mode. More...
struct	cyhal_ethernet_rgmii_pins_t
	Pins to use for MAC to PHY interface for RGMII drive mode. More...
union	cyhal_ethernet_pins_t
	Pin selection according to MAC to PHY drive mode. More...
struct	cyhal_ethernet_1588_timer_val_t
	Configuring 1588 TSU (Time Stamp Unit) timer in the MAC as part of IEEE 1588 (Precision Timing Protocol) enablement. More...
struct	cyhal_ethernet_config_t
	Ethernet configuration. More...
struct	cyhal_ethernet_filter_config_t
	Ethernet MAC filter configuration. More...
struct	cyhal_ether_header_t
	Ethernet Header. More...

Macros
#define	CYHAL_ETHERNET_OBJ_TAG   (0xC025520C)
	< cyhal_ethernet_t field 'tag' set to this value when when initialized
#define	CYHAL_ETHER_IS_NULL_ADDR(ea)
	Return true for NULL Ethernet address (all 0x00) More...
#define	CYHAL_ETHER_IS_UNICAST(ea)   ( ( (uint8 *)(ea)[0]) & 0x01)
	Return true for Unicast Ethernet address.
#define	CYHAL_ETHER_IS_MULTICAST(ea)   ( ( (const uint8 *)(ea) )[0] & 1)
	Return true for Multicast Ethernet address (also returns true for Broadcast address)
#define	CYHAL_ETHER_IS_BROADCAST(ea)
	Return true for Broadcast Ethernet Address (all 0xFF) More...
#define	CYHAL_ETHER_ADDR_CMP(a, b)
	Compare two Ethernet addresses - assumes the pointers can be referenced as shorts. More...
#define	CYHAL_ETHER_ADDR_CPY(s, d)
	Copy an Ethernet address - assumes the pointers can be referenced as shorts. More...

Typedefs
typedef void(*	cyhal_ethernet_event_callback_t) (void *callback_arg, cyhal_ethernet_event_t event)
	Callback handler for Ethernet events.

Enumerations
enum	cyhal_ethernet_clk_src_t {   CYHAL_ETHERNET_CLK_EXT ,   CYHAL_ETHERNET_CLK_INT }
	Reference clock input selection for the Ethernet MAC. More...
enum	cyhal_ethernet_mac_drive_mode_t {   CYHAL_ETHERNET_MII_10 ,   CYHAL_ETHERNET_MII_100 ,   CYHAL_ETHERNET_GMII_1000 ,   CYHAL_ETHERNET_RGMII_10 ,   CYHAL_ETHERNET_RGMII_100 ,   CYHAL_ETHERNET_RGMII_1000 ,   CYHAL_ETHERNET_RMII_10 ,   CYHAL_ETHERNET_RMII_100 ,   CYHAL_ETHERNET_MODE_UNKNOWN }
	Ethernet MAC to PHY drive modes. More...
enum	cyhal_ethernet_filter_type_t {   CYHAL_ETHERNET_FILTER_TYPE_DESTINATION ,   CYHAL_ETHERNET_FILTER_TYPE_SOURCE }
	Configuration to filter Ethernet packets matching MAC address. More...
enum	cyhal_ethernet_event_t {   CYHAL_ETHERNET_EVENT_NONE = 0 ,   CYHAL_ETHERNET_TX_COMPLETE_EVENT = 1 << 1 ,   CYHAL_ETHERNET_TX_ERR_OCCURED_EVENT = 1 << 2 ,   CYHAL_ETHERNET_RX_FRAME_EVENT = 1 << 3 ,   CYHAL_ETHERNET_TSU_SECOND_INC_EVENT = 1 << 4 ,   CYHAL_ETHERNET_DMA_ERR_OCCURED_EVENT = 1 << 5 }
	Enum for Ethernet events More...

Functions
cy_rslt_t	cyhal_ethernet_init (cyhal_ethernet_t *obj, const cyhal_ethernet_config_t *eth_config, const cyhal_ethernet_pins_t *eth_pins, const cyhal_clock_t *clk)
	Initialize the Ethernet MAC and PHY. More...
void	cyhal_ethernet_free (cyhal_ethernet_t *obj)
	Deinitialize an Ethernet object. More...
cy_rslt_t	cyhal_ethernet_init_cfg (cyhal_uart_t *obj, const cyhal_ethernet_configurator_t *cfg)
	Initialize the Ethernet peripheral using a configurator generated configuration struct. More...
void	cyhal_ethernet_register_callback (cyhal_ethernet_t *obj, cyhal_ethernet_event_callback_t callback, void *callback_arg)
	Register an Ethernet callback handler. More...
void	cyhal_ethernet_enable_event (cyhal_ethernet_t *obj, cyhal_ethernet_event_t event, uint8_t intr_priority, bool enable)
	Configure Ethernet events. More...
cy_rslt_t	cyhal_ethernet_transmit_frame (cyhal_ethernet_t *obj, uint8_t *frame_data, uint16_t size)
	Transmits ethernet frame data. More...
cy_rslt_t	cyhal_ethernet_read_frame (cyhal_ethernet_t *obj, uint8_t *frame_data, uint16_t *size)
	Read ethernet frame data. More...
cy_rslt_t	cyhal_ethernet_get_1588_timer_value (cyhal_ethernet_t *obj, cyhal_ethernet_1588_timer_val_t *timer_val)
	Read IEEE 1588 TSU (Time Stamp Unit) programmed timer value. More...
cy_rslt_t	cyhal_ethernet_set_1588_timer_value (cyhal_ethernet_t *obj, const cyhal_ethernet_1588_timer_val_t *timer_val)
	Program IEEE 1588 TSU (Time Stamp Unit) timer programmed. More...
cy_rslt_t	cyhal_ethernet_config_pause (cyhal_ethernet_t *obj, const uint16_t pause_quanta)
	A pause frame includes the period of pause time being requested, in the form of a two-byte (16-bit), unsigned integer (0 through 65535). More...
cy_rslt_t	cyhal_ethernet_transmit_pause_frame (cyhal_ethernet_t *obj, const bool start_pause)
	Transmit a pause frame. More...
uint8_t	cyhal_ethernet_get_num_filter (cyhal_ethernet_t *obj)
	Get the number of MAC filters supported by the device. More...
cy_rslt_t	cyhal_ethernet_set_filter_address (cyhal_ethernet_t *obj, const uint8_t filter_num, const cyhal_ethernet_filter_config_t *config)
	Configure a source or destination MAC filter. More...
cy_rslt_t	cyhal_ethernet_set_promiscuous_mode (cyhal_ethernet_t *obj, const bool enable_promiscuous)
	Enable or disable receiving Ethernet traffic that would normally be excluded by MAC filters. More...
cy_rslt_t	cyhal_ethernet_enable_broadcast_receive (cyhal_ethernet_t *obj, const bool enable_broadcast)
	Enable/disable receiving of broadcast type ethernet frames. More...
cy_rslt_t	cyhal_ethernet_phy_reg_write (cyhal_ethernet_t *obj, const uint8_t reg_number, const uint32_t value)
	Write low level PHY register. More...
cy_rslt_t	cyhal_ethernet_phy_reg_read (cyhal_ethernet_t *obj, const uint8_t reg_number, uint32_t *value)
	Read low level PHY register, cyhal_ethernet_phy_reg_write() for more details on the register access. More...

---

Data Structure Documentation

cyhal_ethernet_mii_pins_t

struct cyhal_ethernet_mii_pins_t

Data Fields
cyhal_gpio_t	mdc	MDC (Management Clock) pin.
cyhal_gpio_t	mdio	MDIO (Management Data) pin bi-direction.
cyhal_gpio_t	tx_clk	Transmit clock PHY to MAC.
cyhal_gpio_t	tx_d0	Transmit data line 0.
cyhal_gpio_t	tx_d1	Transmit data line 1.
cyhal_gpio_t	tx_d2	Transmit data line 2.
cyhal_gpio_t	tx_d3	Transmit data line 3.
cyhal_gpio_t	tx_en	Transmit enable.
cyhal_gpio_t	tx_err	Transmit error signal (Option), make it NULL when not used.
cyhal_gpio_t	rx_clk	Receive clock from PHY to MAC.
cyhal_gpio_t	rx_d0	Receive data line 0.
cyhal_gpio_t	rx_d1	Receive data line 1.
cyhal_gpio_t	rx_d2	Receive data line 2.
cyhal_gpio_t	rx_d3	Receive data line 3.
cyhal_gpio_t	rx_dv	Receive data valid line.
cyhal_gpio_t	rx_err	Receive error signal.
cyhal_gpio_t	rx_crs	Receive carrier sense signal.
cyhal_gpio_t	rx_col	Receive collision detect signal.

cyhal_ethernet_rmii_pins_t

struct cyhal_ethernet_rmii_pins_t

Data Fields
cyhal_gpio_t	mdc	MDC (Management Clock) pin.
cyhal_gpio_t	mdio	MDIO (Management Data) pin bi-direction.
cyhal_gpio_t	ref_clk	Reference clock signal.
cyhal_gpio_t	tx_d0	Transmit data line 0.
cyhal_gpio_t	tx_d1	Transmit data line 1.
cyhal_gpio_t	tx_en	Transmit enable.
cyhal_gpio_t	rx_d0	Receive data line 0.
cyhal_gpio_t	rx_d1	Receive data line 1.
cyhal_gpio_t	rx_dv_crs	Receive data valid and carrier sense signal.
cyhal_gpio_t	rx_err	Receive error signal.

cyhal_ethernet_gmii_pins_t

struct cyhal_ethernet_gmii_pins_t

Data Fields
cyhal_gpio_t	mdc	MDC (Management Clock) pin.
cyhal_gpio_t	mdio	MDIO (Management Data) pin bi-direction.
cyhal_gpio_t	gtx_clk	Transmit clock.
cyhal_gpio_t	tx_d0	Transmit data line 0.
cyhal_gpio_t	tx_d1	Transmit data line 1.
cyhal_gpio_t	tx_d2	Transmit data line 2.
cyhal_gpio_t	tx_d3	Transmit data line 3.
cyhal_gpio_t	tx_d4	Transmit data line 4.
cyhal_gpio_t	tx_d5	Transmit data line 5.
cyhal_gpio_t	tx_d6	Transmit data line 6.
cyhal_gpio_t	tx_d7	Transmit data line 7.
cyhal_gpio_t	tx_en	Transmit enable.
cyhal_gpio_t	tx_err	Transmit error signal.
cyhal_gpio_t	rx_clk	Receive clock signal.
cyhal_gpio_t	rx_d0	Receive data line 0.
cyhal_gpio_t	rx_d1	Receive data line 1.
cyhal_gpio_t	rx_d2	Receive data line 2.
cyhal_gpio_t	rx_d3	Receive data line 3.
cyhal_gpio_t	rx_d4	Receive data line 4.
cyhal_gpio_t	rx_d5	Receive data line 5.
cyhal_gpio_t	rx_d6	Receive data line 6.
cyhal_gpio_t	rx_d7	Receive data line 7.
cyhal_gpio_t	rx_dv	Receive data valid line.
cyhal_gpio_t	rx_err	Receive error signal.
cyhal_gpio_t	rx_crs	Receive carrier sense signal.
cyhal_gpio_t	rx_col	Receive collision detect signal.

cyhal_ethernet_rgmii_pins_t

struct cyhal_ethernet_rgmii_pins_t

Data Fields
cyhal_gpio_t	mdc	MDC (Management Clock) pin.
cyhal_gpio_t	mdio	MDIO (Management Data) pin bi-direction.
cyhal_gpio_t	gtx_clk	Transmit clock.
cyhal_gpio_t	tx_d0	Transmit data line 0.
cyhal_gpio_t	tx_d1	Transmit data line 1.
cyhal_gpio_t	tx_d2	Transmit data line 2.
cyhal_gpio_t	tx_d3	Transmit data line 3.
cyhal_gpio_t	tx_ctl	Transmit control signal used for both transmit enable and transmit error indication.
cyhal_gpio_t	rx_clk	Receive clock.
cyhal_gpio_t	rx_d0	Receive data line 0.
cyhal_gpio_t	rx_d1	Receive data line 1.
cyhal_gpio_t	rx_d2	Receive data line 2.
cyhal_gpio_t	rx_d3	Receive data line 3.
cyhal_gpio_t	rx_ctl	Receive control signal used for both receive enable and receive error indication.

cyhal_ethernet_pins_t

union cyhal_ethernet_pins_t

Data Fields
cyhal_ethernet_mii_pins_t	eth_type_mii	Pin information when drive mode is CYHAL_ETHERNET_MII_10 or CYHAL_ETHERNET_MII_100.
cyhal_ethernet_gmii_pins_t	eth_type_gmii	Pin information when drive mode is CYHAL_ETHERNET_GMII_1000.
cyhal_ethernet_gmii_pins_t	eth_type_rgmii	Pin information when drive mode is CYHAL_ETHERNET_RGMII_10 or CYHAL_ETHERNET_RGMII_100 or CYHAL_ETHERNET_RGMII_1000
cyhal_ethernet_rmii_pins_t	eth_type_rmii	Pin information when drive mode is CYHAL_ETHERNET_RMII_10 or CYHAL_ETHERNET_RMII_100.

cyhal_ethernet_1588_timer_val_t

struct cyhal_ethernet_1588_timer_val_t

Data Fields
uint16_t	secs_upper	Upper 16 bits of seconds value.
uint32_t	secs_lower	Lower 32 bits of seconds value.
uint32_t	nano_secs	Nanoseconds value (30 bits)

cyhal_ethernet_config_t

struct cyhal_ethernet_config_t

Data Fields
cyhal_ethernet_mac_drive_mode_t	drive_mode	Ethernet drive mode configuration.
cyhal_ethernet_clk_src_t	clk_source	Ethernet reference clock source.
uint32_t	ext_clk_freq	External off chip clock source frequency information in Hz If clk_source is CYHAL_ETHERNET_CLK_EXT, this must be non-zero If clk_source is CYHAL_ETHERNET_CLK_INT, this must be zero.

cyhal_ethernet_filter_config_t

struct cyhal_ethernet_filter_config_t

Data Fields
cyhal_ethernet_filter_type_t	filter_type	Ethernet MAC filter for source/destination MAC adress.
uint8_t	mac_addr[6]	Store 6byte Ethernet MAC address.
uint8_t	ignore_bytes	Ignore number of bytes for in the received packet before comparing (filtering) ignore_bytes = 0x01 implies first byte received should not be compared.

cyhal_ether_header_t

struct cyhal_ether_header_t

Data Fields
uint8_t	preamble[CYHAL_ETHER_PREAMBLE_LEN]	Preamble 0xAA,0xAA,0xAA,0xAA,0xAA,0xAA,0xAA, and 0xAB.
uint8_t	ether_dhost[CYHAL_ETHER_ADDR_LEN]	Destination host ethernet MAC.
uint8_t	ether_shost[CYHAL_ETHER_ADDR_LEN]	Source host ethernet MAC.
uint16_t	ether_type	Ethernet Packet Type.

Macro Definition Documentation

CYHAL_ETHER_IS_NULL_ADDR

#define CYHAL_ETHER_IS_NULL_ADDR

(

ea

)

Value:

        ( ( ( (const uint8 *)(ea))[0] |     \
            ( (const uint8 *)(ea))[1] |     \
            ( (const uint8 *)(ea))[2] |     \
            ( (const uint8 *)(ea))[3] |     \
            ( (const uint8 *)(ea))[4] |     \
            ( (const uint8 *)(ea))[5]) == 0)

Return true for NULL Ethernet address (all 0x00)

CYHAL_ETHER_IS_BROADCAST

#define CYHAL_ETHER_IS_BROADCAST

(

ea

)

Value:

        ( ( ( (const uint8 *)(ea) )[0] &        \
            ( (const uint8 *)(ea) )[1] &        \
            ( (const uint8 *)(ea) )[2] &        \
            ( (const uint8 *)(ea) )[3] &        \
            ( (const uint8 *)(ea) )[4] &        \
            ( (const uint8 *)(ea) )[5]) == 0xff)

Return true for Broadcast Ethernet Address (all 0xFF)

CYHAL_ETHER_ADDR_CMP

#define CYHAL_ETHER_ADDR_CMP	(		a,
			b
	)

Value:

                     ( ( ( (const uint16 *)(a))[0] ^ ( (const uint16 *)(b) )[0]) | \
                     ( ( (const uint16 *)(a) )[1] ^ ( (const uint16 *)(b) )[1]) | \
                     ( ( (const uint16 *)(a) )[2] ^ ( (const uint16 *)(b) )[2]))

Compare two Ethernet addresses - assumes the pointers can be referenced as shorts.

CYHAL_ETHER_ADDR_CPY

#define CYHAL_ETHER_ADDR_CPY	(		s,
			d
	)

Value:

        do {                                                \
            ((uint16 *)(d))[0] = ((const uint16 *)(s))[0];  \
            ((uint16 *)(d))[1] = ((const uint16 *)(s))[1];  \
            ((uint16 *)(d))[2] = ((const uint16 *)(s))[2];  \
        } while (0)

Copy an Ethernet address - assumes the pointers can be referenced as shorts.

Enumeration Type Documentation

cyhal_ethernet_clk_src_t

enum cyhal_ethernet_clk_src_t

Reference clock input selection for the Ethernet MAC.

Enumerator
CYHAL_ETHERNET_CLK_EXT	External off chip clock source from IO Pin.
CYHAL_ETHERNET_CLK_INT	Internally generated clock source.

cyhal_ethernet_mac_drive_mode_t

enum cyhal_ethernet_mac_drive_mode_t

Ethernet MAC to PHY drive modes.

Enumerator
CYHAL_ETHERNET_MII_10	Media-Independent Interface (MII) type with link speed upto 10 Mbps.
CYHAL_ETHERNET_MII_100	Media-Independent Interface (MII) type with link speed upto 100 Mbps.
CYHAL_ETHERNET_GMII_1000	Gigabit Media-Independent Interface (GMII) type with link speed upto 1000 Mbps.
CYHAL_ETHERNET_RGMII_10	Reduced Gigabit Media-Independent Interface (RGMII) type with link speed upto 10 Mbps.
CYHAL_ETHERNET_RGMII_100	Reduced Gigabit Media-Independent Interface (RGMII) type with link speed upto 100 Mbps.
CYHAL_ETHERNET_RGMII_1000	Reduced Gigabit Media-Independent Interface (RGMII) type with link speed upto 1000 Mbps.
CYHAL_ETHERNET_RMII_10	Reduced Media-Independent Interface (RMII) type with link speed upto 10 Mbps.
CYHAL_ETHERNET_RMII_100	Reduced Media-Independent Interface (RMII) type with link speed upto 100 Mbps.
CYHAL_ETHERNET_MODE_UNKNOWN	If we fail to set the mode.

cyhal_ethernet_filter_type_t

enum cyhal_ethernet_filter_type_t

Configuration to filter Ethernet packets matching MAC address.

Enumerator
CYHAL_ETHERNET_FILTER_TYPE_DESTINATION	Filter ethernet packet matching Destination MAC address.
CYHAL_ETHERNET_FILTER_TYPE_SOURCE	Filter ethernet packet matching Source MAC address.

cyhal_ethernet_event_t

enum cyhal_ethernet_event_t

Enum for Ethernet events

Enumerator
CYHAL_ETHERNET_EVENT_NONE	No event.
CYHAL_ETHERNET_TX_COMPLETE_EVENT	A message transmission was completed.
CYHAL_ETHERNET_TX_ERR_OCCURED_EVENT	An error occurred while transmitting a message.
CYHAL_ETHERNET_RX_FRAME_EVENT	An ethernet message was received. If filtering is on, or broadcast/promiscuous mode turned off You may get an event, and when you try to read, there will be no packet.
CYHAL_ETHERNET_TSU_SECOND_INC_EVENT	The TSU (Time Stamp Unit) second counter was incremented.
CYHAL_ETHERNET_DMA_ERR_OCCURED_EVENT	DMA xfer with GMAC error.

Function Documentation

cyhal_ethernet_init()

cy_rslt_t cyhal_ethernet_init	(	cyhal_ethernet_t *	obj,
		const cyhal_ethernet_config_t *	eth_config,
		const cyhal_ethernet_pins_t *	eth_pins,
		const cyhal_clock_t *	clk
	)

Initialize the Ethernet MAC and PHY.

It sets the default parameters for Ethernet peripheral, and configures the specifies pins. There multiple drive mode configuration between Ethernet MAC and PHY so the appropriate pin information union member must be populated. The Ethernet MAC can operate either internal clock (PLL) or external clock source via HSIO.

Parameters

[in,out]	obj	Pointer to an Ethernet object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	eth_config	Initial ethernet block configuration contains information regarding the drive mode, reference clock, and reference clock frequency
[in]	eth_pins	Pins for MAC to PHY interface.
[in]	clk	Clock source to use for this instance. If NULL, a dedicated clock divider will be allocated for this instance. If eth_config.clk_source is CYHAL_ETHERNET_CLK_EXT, this must be NULL

Returns

The status of the init request

cyhal_ethernet_free()

void cyhal_ethernet_free

(

cyhal_ethernet_t *

obj

)

Deinitialize an Ethernet object.

Parameters

[in]

obj

Pointer to an Ethernet object

cyhal_ethernet_init_cfg()

cy_rslt_t cyhal_ethernet_init_cfg	(	cyhal_uart_t *	obj,
		const cyhal_ethernet_configurator_t *	cfg
	)

Initialize the Ethernet peripheral using a configurator generated configuration struct.

Parameters

[in]	obj	The Ethernet peripheral to configure
[in]	cfg	Configuration structure generated by a configurator.

Returns

The status of the operation

cyhal_ethernet_register_callback()

void cyhal_ethernet_register_callback	(	cyhal_ethernet_t *	obj,
		cyhal_ethernet_event_callback_t	callback,
		void *	callback_arg
	)

Register an Ethernet callback handler.

This function will be called when one of the events enabled by cyhal_ethernet_enable_event occurs.

Parameters

[in]	obj	Pointer to an Ethernet object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_ethernet_enable_event()

void cyhal_ethernet_enable_event	(	cyhal_ethernet_t *	obj,
		cyhal_ethernet_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure Ethernet events.

When an enabled event occurs, the function specified by cyhal_ethernet_register_callback will be called.

Parameters

[in]	obj	Pointer to an Ethernet object
[in]	event	The Ethernet event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on specified events, False to turn off

cyhal_ethernet_transmit_frame()

cy_rslt_t cyhal_ethernet_transmit_frame	(	cyhal_ethernet_t *	obj,
		uint8_t *	frame_data,
		uint16_t	size
	)

Transmits ethernet frame data.

This functions returns immediately after copying data to MAC internal buffer. Optional step, to monitor actual transmit completion, set callback cyhal_ethernet_register_callback() and event notification cyhal_ethernet_enable_event() CYHAL_ETHERNET_TX_COMPLETE_EVENT . The function return error code CYHAL_ETHERNET_RSLT_TX_FAILED if the MAC internal buffer occupied and busy transmitting.

The frame buffer is a complete Ethernet Header, with the start of the buffer containing the cyhal_ether_header_t structure followed by the data, and room for the CRC (4 bytes) at the end of the buffer. Calculate the buffer size: size = sizeof(cyhal_ether_header_t) + sizeof(uint32_t) + actual data size

Minimum data filled in by Caller: Header:

• ether_dhost (destination mac address)

cyhal_ethernet_transmit_frame() will fill in these parts of the packet: Header:

• preamble (802.3 standard)
• ether_shost (source mac address, this device)
• ether_type (type of Ethernet packet) Footer:
• CRC

++++++++++++++++++++++++++++++++++++++++++++ – | Ethernet | | \ | Header | cyhal_ether_header_t | \ +--------—+---------------------------—+ \ | | | — size of frame_data | Data | CYHAL_ETHER_MAX_DATA bytes | / | | | / +--------—+---------------------------—+ / | Footer | 4-byte CRC | / ++++++++++++++++++++++++++++++++++++++++++++ –

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	frame_data	Pointer to ethernet frame data
[in]	size	Transmit data size in number of bytes (size of frame_data buffer)

Returns

The status of the ethernet frame data transmit request

cyhal_ethernet_read_frame()

cy_rslt_t cyhal_ethernet_read_frame	(	cyhal_ethernet_t *	obj,
		uint8_t *	frame_data,
		uint16_t *	size
	)

Read ethernet frame data.

This function return 0 for size when there is no data is available for readback.

Parameters

[in]	obj	Pointer to an Ethernet object.
[out]	frame_data	Pointer to frame data location
[in,out]	size	[in] The size of frame_data. [out] Received frame data size in number of bytes

Returns

The status of the ethernet frame data transmit request

cyhal_ethernet_get_1588_timer_value()

cy_rslt_t cyhal_ethernet_get_1588_timer_value	(	cyhal_ethernet_t *	obj,
		cyhal_ethernet_1588_timer_val_t *	timer_val
	)

Read IEEE 1588 TSU (Time Stamp Unit) programmed timer value.

Parameters

[in]	obj	Pointer to an Ethernet object.
[out]	timer_val	Pointer to 1588 timer value.

Returns

The status of the 1588 timer value request

cyhal_ethernet_set_1588_timer_value()

cy_rslt_t cyhal_ethernet_set_1588_timer_value	(	cyhal_ethernet_t *	obj,
		const cyhal_ethernet_1588_timer_val_t *	timer_val
	)

Program IEEE 1588 TSU (Time Stamp Unit) timer programmed.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	timer_val	Pointer to 1588 timer value

Returns

The status of the 1588 timer value setup

cyhal_ethernet_config_pause()

cy_rslt_t cyhal_ethernet_config_pause	(	cyhal_ethernet_t *	obj,
		const uint16_t	pause_quanta
	)

A pause frame includes the period of pause time being requested, in the form of a two-byte (16-bit), unsigned integer (0 through 65535).

This number is the requested duration of the pause. The pause time is measured in units of pause "quanta", where each unit is equal to 512 bit times. This interface configures the pause frame. To transmit the pause frame once configured, use cyhal_ethernet_transmit_pause_frame.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	pause_quanta	Pause quanta

Returns

The status of the pause frame configuration request

cyhal_ethernet_transmit_pause_frame()

cy_rslt_t cyhal_ethernet_transmit_pause_frame	(	cyhal_ethernet_t *	obj,
		const bool	start_pause
	)

Transmit a pause frame.

Before it can be used, cyhal_ethernet_config_pause must be called at least once to configure the pause frame.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	start_pause	Start/stop transmitting pause frames True - The pause frames will be transmitted for pause_quanta defined in cyhal_ethernet_config_pause() False - Pause frame transmission is stopped

Returns

The status of the pause frame transmit request

cyhal_ethernet_get_num_filter()

uint8_t cyhal_ethernet_get_num_filter

(

cyhal_ethernet_t *

obj

)

Get the number of MAC filters supported by the device.

Parameters

[in]

obj

Pointer to an Ethernet object.

Returns

The number of filters available

cyhal_ethernet_set_filter_address()

cy_rslt_t cyhal_ethernet_set_filter_address	(	cyhal_ethernet_t *	obj,
		const uint8_t	filter_num,
		const cyhal_ethernet_filter_config_t *	config
	)

Configure a source or destination MAC filter.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	filter_num	MAC filter number to be configured. This must be less than the value returned by \ref cyhal_ethernet_get_num_filter. If this filter number was previously configured, it will be reconfigured.
[in]	config	MAC filter configuration.

Returns

The status of the MAC configuration request.

cyhal_ethernet_set_promiscuous_mode()

cy_rslt_t cyhal_ethernet_set_promiscuous_mode	(	cyhal_ethernet_t *	obj,
		const bool	enable_promiscuous
	)

Enable or disable receiving Ethernet traffic that would normally be excluded by MAC filters.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	enable_promiscuous	True (default behavior) - MAC configured to capture all the network traffic False - Ethernet MAC captures the ethernet frames as per the MAC filter setting

Returns

The status of the promiscuous mode enable/disable request.

cyhal_ethernet_enable_broadcast_receive()

cy_rslt_t cyhal_ethernet_enable_broadcast_receive	(	cyhal_ethernet_t *	obj,
		const bool	enable_broadcast
	)

Enable/disable receiving of broadcast type ethernet frames.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	enable_broadcast	True (default behavior) - MAC is configured to capture broadcast type frames. False - MAC will filter broadcast frames; so no broadcast frames passed on to upper layers.

Returns

The status of the broadcast enable/disable request.

cyhal_ethernet_phy_reg_write()

cy_rslt_t cyhal_ethernet_phy_reg_write	(	cyhal_ethernet_t *	obj,
		const uint8_t	reg_number,
		const uint32_t	value
	)

Write low level PHY register.

This interface is to access Ethernet PHY registers specified in IEEE 802.3 standard. There is basic register set address range 00h - 0Fh and vendor specific address range 10h to 1Fh. For details on the vendor specific registers, see the Ethernet PHY datasheet. Ethernet HAL driver don't perform vendor specific configuration and control hence the interface provided to user level.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	reg_number	Ethernet PHY register number.
[in]	value	Value to be written into register.

Returns

The status of the Ethernet PHY register write request.

cyhal_ethernet_phy_reg_read()

cy_rslt_t cyhal_ethernet_phy_reg_read	(	cyhal_ethernet_t *	obj,
		const uint8_t	reg_number,
		uint32_t *	value
	)

Read low level PHY register, cyhal_ethernet_phy_reg_write() for more details on the register access.

Parameters

[in]	obj	Pointer to an Ethernet object.
[in]	reg_number	Ethernet PHY register number.
[out]	value	Value readback from the PHY

Returns

The status of the Ethernet PHY register read request.