Group_ecm_functions

General Description

• The ECM library internally creates a thread; the created threads are executed with the "CY_RTOS_PRIORITY_ABOVENORMAL" priority. The definition of the CY_RTOS_PRIORITY_ABOVENORMAL macro is located at "libs/abstraction-rtos/include/COMPONENT_FREERTOS/cyabs_rtos_impl.h".
• ECM APIs are thread-safe.
• All ECM APIs except cy_ecm_init and cy_ecm_deinit are blocking APIs.
• All application callbacks invoked by the ECM will be running in the context of the ECM; the pointers passed as the argument in the callback function will be freed once the function returns.
• For the APIs that expect cy_ecm_interface_t as an argument, unless a specific interface type has been called out in the description of the API, any valid ECM interface type can be passed as an argument to the API.

Functions
cy_rslt_t	cy_ecm_init (void)
	Does general allocation and initialization of resources needed for the library. More...
cy_rslt_t	cy_ecm_deinit (void)
	Releases the resources allocated in the cy_ecm_init function. More...
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. More...
cy_rslt_t	cy_ecm_set_promiscuous_mode (cy_ecm_t ecm_handle, bool is_promiscuous_mode)
	Enable or Disable the promiscuous mode. More...
cy_rslt_t	cy_ecm_broadcast_disable (cy_ecm_t ecm_handle, bool is_broadcast_disable)
	Enable or Disable the incoming broadcast packets. More...
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. More...
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. More...
cy_rslt_t	cy_ecm_disconnect (cy_ecm_t ecm_handle)
	Brings down the interface. More...
cy_rslt_t	cy_ecm_register_event_callback (cy_ecm_t ecm_handle, cy_ecm_event_callback_t event_callback)
	Registers an event callback to monitor the connection and IP address change events. More...
cy_rslt_t	cy_ecm_deregister_event_callback (cy_ecm_t ecm_handle, cy_ecm_event_callback_t event_callback)
	Deregisters an event callback. More...
cy_rslt_t	cy_ecm_get_link_status (cy_ecm_t ecm_handle, bool *status)
	Provides the status of the link. More...
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. More...
cy_rslt_t	cy_ecm_get_ipv6_address (cy_ecm_t ecm_handle, cy_ecm_ipv6_type_t ipv6_addr_type, cy_ecm_ip_address_t *ip_addr)
	Retrieves the IPv6 address of the given interface. More...
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. More...
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. More...
cy_rslt_t	cy_ecm_get_mac_address (cy_ecm_t ecm_handle, cy_ecm_mac_t *mac_addr)
	Retrieves the MAC address of the gateway for the Ethernet interface. More...
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. More...
cy_rslt_t	cy_ecm_get_link_speed (cy_ecm_t ecm_handle, cy_ecm_duplex_t *duplex, cy_ecm_phy_speed_t *speed)
	Retrieves the configured ethernet speed and duplex mode. More...
cy_rslt_t	cy_ecm_ethif_deinit (cy_ecm_t *ecm_handle)
	Deinitializes the Ethernet physical driver. More...

Function Documentation

cy_ecm_init()

cy_rslt_t cy_ecm_init

(

void

)

Does general allocation and initialization of resources needed for the library.

This API function must be called before using any other Ethernet Connection Manager API.

Note

cy_ecm_init and cy_ecm_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns

CY_RSLT_SUCCESS if ECM initialization was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_NW_INIT_ERROR
CY_RSLT_ECM_MUTEX_ERROR

cy_ecm_deinit()

cy_rslt_t cy_ecm_deinit

(

void

)

Releases the resources allocated in the cy_ecm_init function.

Note

cy_ecm_init and cy_ecm_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Returns

CY_RSLT_SUCCESS if ECM de-initialization was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_ECM_INIT_ERROR

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.

This function should be called after calling cy_ecm_init. The handle to the ECM instance is returned via the handle pointer supplied by the user on success.

Note

1. Ethernet Connection Manager library returns error as required ethernet phy driver callbacks functions were not passed with this API.
2. As a part of cy_ecm_ethif_init, Ethernet driver initialization is called, which does GPIO and clock divider settings for the given physical configurations. But, Ethernet driver deinitialization is not available to clear these clock and GPIO settings.Hence, cy_ecm_ethif_init cannot be called more than once in a single session, with different physical configurations.
3. If either speed or duplex mode is set to AUTO, the Autonegotiation will be enabled. Application can call cy_ecm_get_link_speed, to check the speed and duplex mode configured.

Parameters

[in]	eth_idx	: Ethernet port to be initialized
[in]	phy_callbacks	: Structure containing the Ethernet physical driver callback implementation for required ethernet PHY chip.
[out]	ecm_handle	: Pointer to store the ECM handle allocated by this function on a successful return. Caller should not free the handle directly. You should invoke cy_ecm_ethif_deinit to free the handle.

Returns

CY_RSLT_SUCCESS if ECM initialization was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR
CY_RSLT_ECM_ERROR_NOMEM
CY_RSLT_ECM_INIT_ERROR

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.

This function configures the ethernet MAC to enable or disable the promiscuous mode. By default promiscuous mode will be disabled. This function should be called after calling cy_ecm_ethif_init ECM API.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init.
[in]	is_promiscuous_mode	: true enables promiscuous mode, if false then this is disabled.

Returns

CY_RSLT_SUCCESS if ECM configuration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR

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.

This function configures the ethernet MAC to enable or disable the incoming broadcast packets. By default broadcast packets are accepted. This function should be called after calling cy_ecm_ethif_init ECM API.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init.
[in]	is_broadcast_disable	: false broadcasts are accepted, if true they are rejected.

Returns

CY_RSLT_SUCCESS if ECM configuration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR

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.

This function configures the filter address to the ethernet MAC to filter the receiving packets. This function should be called after calling cy_ecm_ethif_init ECM API.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init.
[in]	filter_address	: Array containing list of address to be filtered.
[in]	filter_address_count	: Total count of addresses to be filtered. Maximum supported is CY_ECM_MAX_FILTER_ADDRESS.

Returns

CY_RSLT_SUCCESS if ECM configuration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR
CY_RSLT_ECM_ERROR

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.

This function brings up the network interface. This function should be called after calling the cy_ecm_ethif_init ECM API.

Note

If DHCP or static IP is configured from device configurator, then the parameter static_ip_addr will be ignored.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[in]	static_ip_addr	: Configuration of the static IP address. If NULL, the IP address is created using DHCP.
[out]	ip_addr	: Pointer to return the IPv4 address (optional)

Returns

CY_RSLT_SUCCESS if ECM configuration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR
CY_RSLT_ECM_BAD_STATIC_IP
CY_RSLT_ECM_INTERFACE_ERROR
CY_RSLT_MODULE_ECM_ALREADY_CONNECTED
CY_RSLT_ECM_ERROR

cy_ecm_disconnect()

cy_rslt_t cy_ecm_disconnect

(

cy_ecm_t

ecm_handle

)

Brings down the interface.

This function should be called after calling the cy_ecm_connect ECM API.

Parameters

[in]

ecm_handle

ECM handle created using cy_ecm_ethif_init.

Returns

CY_RSLT_SUCCESS if ECM configuration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_MODULE_ECM_NOT_INITIALIZED
CY_RSLT_ECM_MUTEX_ERROR
CY_RSLT_ECM_INTERFACE_ERROR
CY_RSLT_MODULE_ECM_NOT_CONNECTED
CY_RSLT_ECM_ERROR

cy_ecm_register_event_callback()

cy_rslt_t cy_ecm_register_event_callback	(	cy_ecm_t	ecm_handle,
		cy_ecm_event_callback_t	event_callback
	)

Registers an event callback to monitor the connection and IP address change events.

This is an optional registration; use it if the application needs to monitor events across disconnection and reconnection.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[in]	event_callback	: Callback function to be invoked for event notification. The callback will be executed in the context of the ECM.

Returns

CY_RSLT_SUCCESS if application callback registration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_ERROR

cy_ecm_deregister_event_callback()

cy_rslt_t cy_ecm_deregister_event_callback	(	cy_ecm_t	ecm_handle,
		cy_ecm_event_callback_t	event_callback
	)

Deregisters an event callback.

Parameters

[in]	ecm_handle	: ECM handle obtained by cy_ecm_ethif_init
[in]	event_callback	: Callback function to deregister from getting notifications

Returns

CY_RSLT_SUCCESS if application callback de-registration was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_ERROR

cy_ecm_get_link_status()

cy_rslt_t cy_ecm_get_link_status	(	cy_ecm_t	ecm_handle,
		bool *	status
	)

Provides the status of the link.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	status	: Pointer to store the link status(0=down, 1=up)

Returns

CY_RSLT_SUCCESS if link status reading was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_ERROR

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.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	ip_addr	: Pointer to an IP address structure (or) an IP address structure array

Returns

CY_RSLT_SUCCESS if IP address get is successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_IP_ADDR_ERROR

cy_ecm_get_ipv6_address()

cy_rslt_t cy_ecm_get_ipv6_address	(	cy_ecm_t	ecm_handle,
		cy_ecm_ipv6_type_t	ipv6_addr_type,
		cy_ecm_ip_address_t *	ip_addr
	)

Retrieves the IPv6 address of the given interface.

Note: Currently, this API supports only the CY_ECM_IPV6_LINK_LOCAL type.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[in]	ipv6_addr_type	: IPv6 address type
[out]	ip_addr	: Pointer to a structure filled with IP address

Returns

CY_RSLT_SUCCESS if IPv6 interface is up and IPv6 address is ready; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_IPV6_GLOBAL_ADDRESS_NOT_SUPPORTED
CY_RSLT_ECM_IPV6_INTERFACE_NOT_READY
CY_RSLT_ECM_ERROR

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.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	gateway_addr	: Pointer to a structure filled with the gateway IP address

Returns

CY_RSLT_SUCCESS if retrieval of the gateway IP address was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_GATEWAY_ADDR_ERROR
CY_RSLT_ECM_ERROR

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.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	net_mask_addr	: Pointer to a structure filled with the subnet mask address

Returns

CY_RSLT_SUCCESS if retrieval of the subnet mask address was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_NETMASK_ADDR_ERROR
CY_RSLT_ECM_ERROR

cy_ecm_get_mac_address()

cy_rslt_t cy_ecm_get_mac_address	(	cy_ecm_t	ecm_handle,
		cy_ecm_mac_t *	mac_addr
	)

Retrieves the MAC address of the gateway for the Ethernet interface.

Uses Address Resolution Protocol (ARP) to retrieve the gateway MAC address.

This function is a blocking call and uses an internal timeout while running ARP.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	mac_addr	: Pointer to a MAC address structure which is filled with the gateway's MAC address on successful return.

Returns

CY_RSLT_SUCCESS if retrieval of the gateway MAC address was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_GATEWAY_MAC_ADDR_ERROR
CY_RSLT_ECM_ERROR

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.

This function is a blocking call; it returns after the specified timeout.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[in]	ip_addr	: Pointer to the destination IP address structure to which the ping request will be sent
[in]	timeout_ms	: Ping request timeout in milliseconds
[out]	elapsed_ms	: Pointer to store the round-trip time (in milliseconds); i.e., the time taken to receive the ping response from the destination.

Returns

CY_RSLT_SUCCESS if ping to the IP address was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_PING_REQUEST_TIMEOUT
CY_RSLT_ECM_PING_FAILURE
CY_RSLT_ECM_MUTEX_ERROR

cy_ecm_get_link_speed()

cy_rslt_t cy_ecm_get_link_speed	(	cy_ecm_t	ecm_handle,
		cy_ecm_duplex_t *	duplex,
		cy_ecm_phy_speed_t *	speed
	)

Retrieves the configured ethernet speed and duplex mode.

Parameters

[in]	ecm_handle	: ECM handle created using cy_ecm_ethif_init
[out]	duplex	: Pointer to cy_ecm_duplex_t enum which is filled with the duplex mode on successful return
[out]	speed	: Pointer to cy_ecm_speed_t enum which is filled with the link speed on successful return

Returns

CY_RSLT_SUCCESS if retrieval of the link speed and mode was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_ERROR

cy_ecm_ethif_deinit()

cy_rslt_t cy_ecm_ethif_deinit

(

cy_ecm_t *

ecm_handle

)

Deinitializes the Ethernet physical driver.

Disables Ethernet port, brings down the network stack, and frees the handle. This function should be called after calling cy_ecm_ethif_init.

Parameters

[in,out]

ecm_handle

: Pointer containing the ECM handle created using cy_ecm_ethif_init

Returns

CY_RSLT_SUCCESS if ECM de-initialization was successful; an error code on failure. Important error code related to this API function are:
CY_RSLT_MODULE_ECM_BADARG
CY_RSLT_ECM_MUTEX_ERROR
CY_RSLT_MODULE_ECM_NOT_INITIALIZED