Ethernet Connection Manager Library
Overview

ECM is a library which helps application developers to manage Ethernet Connectivity. The library provides a set of APIs that can be used to establish and monitor ethernet connections on Infineon platforms that support ethernet connectivity. The library APIs are thread-safe. The library monitors the ethernet connection and can notifies connection state changes through an event notification mechanism.

Features and Functionality

The current implementation has the following features and functionality:

  • Supports upto 4 source and destination address filtering.
  • Supports for enabling and disabling of receiving the broadcast messages.
  • Supports for enable/disable of promiscous mode.
  • Exposes ethernet APIs to configure, connect and disconnect from the network.
  • Connection monitoring: Monitors active connections and link events. Notifies the connection state change through event notification registration mechanism.
  • This library is part of ModusToolBox framework that supports connectivity applications based on FreeRTOS, lwIP, and mbed TLS.
  • The library is built on top of the abstraction-rtos library that provides the RTOS abstraction API for FreeRTOS.

Supported Platforms

This library and its features are supported on the following Infineon platforms:

Quick Start

Follow below steps to enable and configure ethernet,

To pull ethernet-phy-driver create the following *.mtb* file in deps folder.

Provide PHY operation callback functions to Ethernet Connection Manager by invoking cy_ecm_ethif_init API function. Refer Ethernet PHY Driver API documentation for API documentation of cy_ecm_ethif_init API function.

Ethernet is not a deep sleep enabled IP, hence system should always be in active mode. Open design.modus file and do the following configuration settings in the ModusToolbox™ Device Configurator.

  • Switch to the "System" tab.
  • Select Resource->Power.
  • In "RTOS" section, "System Idle Power Mode" should be set to "Active" from the drop-down.
  • Save the configuration to generate the necessary code.

To enable ethernet configurations on XMC7200 Evaluation Kit (KIT_XMC72_EVK), open design.modus file and do the following configuration settings in the ModusToolbox™ Device Configurator.

  • Switch to the "Peripherals" tab.
  • Select Communication->"Ethernet 1" for KIT_XMC72_EVK device.
  • In "Ethernet - Parameters" pane, configure interface type "PHY Interconnect" to "RGMII" from the drop-down.
  • Configure PHY driver "PHY device" to "DP83867IR" from the drop-down.
  • Enable/Disable "Autonegotiation" (default is enable).
  • Configure "PHY speed" (10/100/1000 Mbits/sec) based on the device.
  • Configure "PHY Duplex mode" (default Full Duplex).
  • NOTE: "PHY speed" and "PHY Duplex Mode" options are visible only when the "Autonegotiation" is disabled.
  • Configure "Mac Address".
  • Enable "Promiscuous mode" (default is disable).
  • Enable "Accept Broadcast Frames" (default is enable).
  • Configure "Mac Reference Clock" (default is External clk).
  • Configure "Nvic Mux Interrupt number". This will be enabled, if devices have separate Nvic interrupt lines. (default is 3).
  • Configure static IP or use DHCP (default is use DHCP).
  • To configure pin connections, refer "Quick Start" section of Ethernet PHY Driver readme documentation
  • Save the configuration to generate the necessary code.

To enable ethernet configurations on XMC7100 Evaluation Kit (KIT_XMC71_EVK_LITE_V1), open design.modus file and do the following configuration settings in the ModusToolbox™ Device Configurator.

  • Switch to the "Peripherals" tab.
  • Select Communication->"Ethernet 1" for KIT_XMC71_EVK_LITE_V1 device.
  • In "Ethernet - Parameters" pane, configure interface type "PHY Interconnect" to "RMII" from the drop-down.
  • Configure PHY driver "PHY device" to "DP83825I" from the drop-down.
  • Enable/Disable "Autonegotiation" (default is enable).
  • Configure "PHY speed" (10/100 Mbits/sec) based on the device.
  • Configure "PHY Duplex mode" (default Full Duplex).
  • NOTE: "PHY speed" and "PHY Duplex Mode" options are visible only when the "Autonegotiation" is disabled.
  • Configure "Mac Address".
  • Enable "Promiscuous mode" (default is disable).
  • Enable "Accept Broadcast Frames" (default is enable).
  • Configure "Mac Reference Clock" (default is External clk).
  • Configure "Nvic Mux Interrupt number". This will be enabled, if devices have separate Nvic interrupt lines. (default is 3).
  • Configure static IP or use DHCP (default is use DHCP).
  • To configure pin connections, refer "Quick Start" section of Ethernet PHY Driver readme documentation
  • Save the configuration to generate the necessary code.

Add the CY_DISABLE_XMC7000_DATA_CACHE macro to the DEFINES in the code example's Makefile to disable data cache. The Makefile entry would look like as follows:

DEFINES+=CY_DISABLE_XMC7000_DATA_CACHE

The ECM library disables all the debug log messages by default. To enable log messages, the application must perform the following:

  1. Add the ENABLE_ECM_LOGS macro to the DEFINES in the code example's Makefile. The Makefile entry would look like as follows:
    DEFINES+=ENABLE_ECM_LOGS
  2. Call the cy_log_init() function provided by the cy-log module. cy-log is part of the connectivity-utilities library. See *connectivity-utilities library API documentation. Add the CYBSP_ETHERNET_CAPABLE build configuration to enable the ethernet functionality. The Makefile entry should look like as follows:
    DEFINES+=CYBSP_ETHERNET_CAPABLE

Code Snippets

Snippet 1: Init

This code snippet demonstrates the initialization ethernet driver, network stack and configuration structures required for creating an ECM client handle and and usage of the cy_ecm_ethif_init() API function.

cy_ecm_t ecm_handle;
cy_ecm_phy_callbacks_t eth_phy_callbacks =
{
.phy_init = cy_eth_phy_init,
.phy_configure = cy_eth_phy_configure,
.phy_enable_ext_reg = cy_eth_phy_enable_ext_reg,
.phy_discover = cy_eth_phy_discover,
.phy_get_auto_neg_status = cy_eth_phy_get_auto_neg_status,
.phy_get_link_partner_cap = cy_eth_phy_get_link_partner_cap,
.phy_get_linkspeed = cy_eth_phy_get_linkspeed,
.phy_get_linkstatus = cy_eth_phy_get_linkstatus,
.phy_reset = cy_eth_phy_reset
};
void snippet_ecm_ethernet_init( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Initialize the ECM Library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
CY_ECM_INTERFACE_ETH1
@ CY_ECM_INTERFACE_ETH1
Interface for Ethernet port 1.
Definition: cy_ecm.h:49
cy_ecm_ethif_init
cy_rslt_t cy_ecm_ethif_init(cy_ecm_interface_t eth_idx, cy_ecm_phy_callbacks_t *phy_callbacks, cy_ecm_t *ecm_handle)
Initializes the Ethernet physical driver, enables Ethernet port, and brings up the network stack.
cy_ecm_init
cy_rslt_t cy_ecm_init(void)
Does general allocation and initialization of resources needed for the library.
cy_ecm_t
void * cy_ecm_t
Ethernet Connection Manager handle.
Definition: cy_ecm.h:126
cy_ecm_phy_callbacks_t
Structure used to pass the callback function implementation for PHY related operations.
Definition: cy_ecm.h:233
cy_ecm_phy_callbacks_t::phy_init
cy_ecm_phy_init phy_init
Function pointer for Ethernet PHY Init.
Definition: cy_ecm.h:234

Snippet 2: Configure

This code snippet demonstrates how to configure the ethernet features like setting promiscuous mode, broadcast packet disabling, address filtering and and usage of the cy_ecm_set_promiscuous_mode(), cy_ecm_set_broadcast_disable() and cy_ecm_set_filter_address() API functions.

void snippet_ecm_ethernet_features_enable( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
bool is_promiscuous_mode = true;
uint8_t filter_address_count;
cy_ecm_filter_address_t filter_address;
/* Initialize the ECM Library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with the provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Configure the Ethernet driver to enable promiscuous mode */
result = cy_ecm_set_promiscuous_mode( ecm_handle, is_promiscuous_mode );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Configure the Ethernet driver to enable broadcast frames to be received */
result = cy_ecm_broadcast_disable( ecm_handle, false );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Configure the Ethernet driver to disable all the incoming broadcast messages */
result = cy_ecm_broadcast_disable( ecm_handle, true );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
filter_address_count = 1;
filter_address.filter_type = CY_ECM_FILTER_TYPE_SOURCE;
memset( &( filter_address.filter_addr[0] ), 0xFF, CY_ECM_MAC_ADDR_LEN );
filter_address.ignoreBytes = 0x00;
/* Configure the Ethernet driver to enable promiscuous mode */
result = cy_ecm_set_filter_address( ecm_handle, &filter_address, filter_address_count );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
CY_ECM_FILTER_TYPE_SOURCE
@ CY_ECM_FILTER_TYPE_SOURCE
filter on the source address
Definition: cy_ecm.h:101
cy_ecm_set_promiscuous_mode
cy_rslt_t cy_ecm_set_promiscuous_mode(cy_ecm_t ecm_handle, bool is_promiscuous_mode)
Enable or Disable the promiscuous mode.
cy_ecm_set_filter_address
cy_rslt_t cy_ecm_set_filter_address(cy_ecm_t ecm_handle, cy_ecm_filter_address_t *filter_address, uint8_t filter_address_count)
Filter the receiving packets with the configured source or destination filter address.
cy_ecm_broadcast_disable
cy_rslt_t cy_ecm_broadcast_disable(cy_ecm_t ecm_handle, bool is_broadcast_disable)
Enable or Disable the incoming broadcast packets.
CY_ECM_MAC_ADDR_LEN
#define CY_ECM_MAC_ADDR_LEN
MAC address length
Definition: cy_ecm.h:30
cy_ecm_filter_address_t
Structure containing the configuration parameters to configure Ethernet PHY and MAC to filter the add...
Definition: cy_ecm.h:223
cy_ecm_filter_address_t::filter_addr
uint8_t filter_addr[CY_ECM_MAC_ADDR_LEN]
Address to be filtered.
Definition: cy_ecm.h:225
cy_ecm_filter_address_t::ignoreBytes
uint8_t ignoreBytes
For example, ignoreBytes = 0x01 implies that the first byte received should not be compared.
Definition: cy_ecm.h:226
cy_ecm_filter_address_t::filter_type
cy_ecm_filter_type_t filter_type
Type of address to be filtered.
Definition: cy_ecm.h:224

Snippet 3: Connect

This code snippet demonstrates how to establish a connection to the ethernet and bring network up using the cy_ecm_connect() API function.

static cy_ecm_ip_address_t ip_addr;
void snippet_ecm_connect( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Initialize the ECM library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with the provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Connect to the Ethernet interface and bring up the network */
result = cy_ecm_connect( ecm_handle, NULL, &ip_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
cy_ecm_connect
cy_rslt_t cy_ecm_connect(cy_ecm_t ecm_handle, cy_ecm_ip_setting_t *static_ip_addr, cy_ecm_ip_address_t *ip_addr)
Brings up the interface and configure to corresponding Ethernet port.
cy_ecm_ip_address_t
Structure used to set or receive the IP address information to or from the underlying network stack.
Definition: cy_ecm.h:200

Snippet 4: Get IP address

This code snippet demonstrates how to establish a connection to the ethernet and get IP address using the cy_ecm_get_ip_address() API function.

static cy_ecm_ip_address_t gateway_addr, net_mask_addr;
void snippet_ecm_get_ip_address( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Initialize the ECM library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with the provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Connect to the Ethernet interface and bring up the network */
result = cy_ecm_connect( ecm_handle, NULL, &ip_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/*. Return the interface IP address */
result = cy_ecm_get_ip_address( ecm_handle, &ip_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/*. Return gateway IP address */
result = cy_ecm_get_gateway_address( ecm_handle, &gateway_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/*. Return the netmask IP address */
result = cy_ecm_get_netmask_address( ecm_handle, &net_mask_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
cy_ecm_get_ip_address
cy_rslt_t cy_ecm_get_ip_address(cy_ecm_t ecm_handle, cy_ecm_ip_address_t *ip_addr)
Retrieves the IPv4 address of the given interface.
cy_ecm_get_netmask_address
cy_rslt_t cy_ecm_get_netmask_address(cy_ecm_t ecm_handle, cy_ecm_ip_address_t *net_mask_addr)
Retrieves the subnet mask address of the given interface.
cy_ecm_get_gateway_address
cy_rslt_t cy_ecm_get_gateway_address(cy_ecm_t ecm_handle, cy_ecm_ip_address_t *gateway_addr)
Retrieves the gateway IP address of the given interface.

Snippet 5: ping

This code snippet demonstrates how to establish a connection to the ethernet and ping using the cy_ecm_ping() API function.

void snippet_ecm_ping( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
uint32_t elapsed_time_ms;
/* Initialize the ECM library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with the provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Connect to the Ethernet interface and bring up the network */
result = cy_ecm_connect( ecm_handle, NULL, &ip_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/*. Return gateway IP address */
result = cy_ecm_get_gateway_address( ecm_handle, &gateway_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/*. Return the gateway MAC address */
result = cy_ecm_ping( ecm_handle, &gateway_addr, 3000, &elapsed_time_ms );
(void)elapsed_time_ms;
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
cy_ecm_ping
cy_rslt_t cy_ecm_ping(cy_ecm_t ecm_handle, cy_ecm_ip_address_t *ip_addr, uint32_t timeout_ms, uint32_t *elapsed_ms)
Sends a ping request to the given IP address.

Snippet 6: Deinit

This code snippet demonstrates how to disconnect, bring the network down and deinit the ECM ping using the cy_ecm_deinit() API function.

void snippet_ecm_deinit( void )
{
/* Status variables for various operations */
cy_rslt_t result = CY_RSLT_SUCCESS;
/* Initialize the ECM library and network stack */
result = cy_ecm_init();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Initialize the Ethernet driver with the provided configurations */
result = cy_ecm_ethif_init( CY_ECM_INTERFACE_ETH1, &eth_phy_callbacks, &ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Connect to the Ethernet interface and bring up the network */
result = cy_ecm_connect( ecm_handle, NULL, &ip_addr );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Bring down the network stack */
result = cy_ecm_disconnect( ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Deinitialize ecm_handle */
result = cy_ecm_ethif_deinit( ecm_handle );
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
/* Deinitialize the ECM library */
result = cy_ecm_deinit();
if( result != CY_RSLT_SUCCESS )
{
/* Failure path */
}
}
cy_ecm_disconnect
cy_rslt_t cy_ecm_disconnect(cy_ecm_t ecm_handle)
Brings down the interface.
cy_ecm_deinit
cy_rslt_t cy_ecm_deinit(void)
Releases the resources allocated in the cy_ecm_init function.
cy_ecm_ethif_deinit
cy_rslt_t cy_ecm_ethif_deinit(cy_ecm_t *ecm_handle)
Deinitializes the Ethernet physical driver.