Ethernet routines enable communication over an Ethernet-based IP network. More...

Typedefs
typedef void(*	net_icmp_cb_t )(icmpEvent event)
	ICMP Event callback function.

Enumerations
enum	arpCacheType { arpCacheFixedIP, arpCacheTemporaryIP }
	ARP Cache Entry types. More...

enum	icmpEvent { icmpEventSuccess = 0, icmpEventTimeout }
	ICMP (ping) Callback Events. More...

enum	ethLinkEvent { ethLinkDown = 0, ethLinkUp_10MHalfDuplex, ethLinkUp_10MFullDuplex, ethLinkUp_100MHalfDuplex, ethLinkUp_100MFullDuplex, ethLinkUp_1GHalfDuplex, ethLinkUp_1GFullDuplex }
	Ethernet Link Callback Events. More...

enum	dhcpClientOption { dhcpClientIPaddress = 0, dhcpClientNTPservers = 42, dhcpClientBootfileName = 67 }
	DHCP Client Callback Events. More...

Functions
netStatus	arp_cache_ip (uint32_t if_num, const uint8_t *ip_addr, arpCacheType type)
	Determine whether the ARP table has MAC address resolved for requested IP address.

netStatus	arp_cache_mac (uint32_t if_num, const uint8_t *mac_addr)
	Determine whether the ARP table has IP address resolved for requested MAC address.

netStatus	arp_get_ip (const uint8_t mac_addr, uint8_t ip_addr)
	Get IP address from the ARP cache.

netStatus	arp_get_mac (const uint8_t ip_addr, uint8_t mac_addr)
	Get MAC address from the ARP cache.

netStatus	dhcp_disable (uint32_t if_num)
	Disable Dynamic Host Configuration at runtime.

void	eth_link_notify (uint32_t if_num, ethLinkEvent event)
	Notify the user of Ethernet link state change event.

void	dhcp_client_notify (uint32_t if_num, dhcpClientOption opt, const uint8_t *val, uint32_t len)
	Notify the user of DHCP event or extended DHCP option.

netStatus	icmp_ping (const uint8_t *ip_addr, net_icmp_cb_t cb_func)
	Start ICMP ping process.

Description

Ethernet routines enable communication over an Ethernet-based IP network.

Ethernet is a networking technology for local area networks (LANs). Ethernet is standardized as IEEE 802.3. Ethernet is today the de-facto standard for wired LAN technologies. Although the Ethernet standards comprise several wiring and signalling variants (such as coaxial cables), today most systems use twisted pair and fibre optic links in conjunction with hubs or switches. Microcontroller devices support typically data rates between 10 and 100 megabits per second..

Systems communicating over Ethernet divide a stream of data into shorter pieces called frames. Each frame contains source and destination addresses and error-checking data so that damaged data can be detected and re-transmitted.

Computers communicating via Ethernet (stations) are sending each other data packets in short pieces called frames: blocks of data are exchanged individually. Each station is given a unique 48-bit MAC address. The MAC addresses are used to identify the destination and the source of every data packet. Ethernet establishes link level connections, which can be defined using both the destination and source IP addresses. After reception, the receiving station uses the destination address to determine whether the transmission is relevant or should be ignored. Normally, packets addressed to other Ethernet stations are ignored. All generations of Ethernet are using the same frame formats, so that they can be readily interconnected through bridging.

Note: For more information about the configuration please visit the Ethernet page.

Typedef Documentation

void(* net_icmp_cb_t)(icmpEvent event)

ICMP Event callback function.

Parameters

[in] event - ICMP event as defined in icmpEvent.

Is the type definition for the ICMP callback function. Users must provide the function. The callback function uses the event argument to signal one of the following ICMP events:

Event	Description
icmpEventSuccess	Remote host responded to ping.
icmpEventTimeout	Ping session has timed out, remote host did not respond.

Parameter for:

icmp_ping

Enumeration Type Documentation

enum arpCacheType

ARP Cache Entry types.

Parameter for:

arp_cache_ip

Enumerator:

arpCacheFixedIP	Fixed IP address is refreshed after timeout.
arpCacheTemporaryIP	Temporary IP address is removed after timeout.

enum dhcpClientOption

DHCP Client Callback Events.

Option	Event	Description
0	dhcpClientIPaddress	IP address change event.
42	dhcpClientNTPservers	NTP Servers option.
67	dhcpClientBootfileName	Bootfile name option.

Parameter for:

dhcp_client_notify

Enumerator:

dhcpClientIPaddress	IP address change event.
dhcpClientNTPservers	NTP Servers option.
dhcpClientBootfileName	Bootfile name option.

enum ethLinkEvent

Ethernet Link Callback Events.

Parameter for:

eth_link_notify

Enumerator:

ethLinkDown	Link down.
ethLinkUp_10MHalfDuplex	Link up (10 MBit half duplex)
ethLinkUp_10MFullDuplex	Link up (10 MBit full duplex)
ethLinkUp_100MHalfDuplex	Link up (100 MBit half duplex)
ethLinkUp_100MFullDuplex	Link up (100 MBit full duplex)
ethLinkUp_1GHalfDuplex	Link up (1 GBit half duplex)
ethLinkUp_1GFullDuplex	Link up (1 GBit full duplex)

enum icmpEvent

ICMP (ping) Callback Events.

Parameter for:

net_icmp_cb_t

Enumerator:

icmpEventSuccess	Pinged Host responded.
icmpEventTimeout	Timeout, no ping response received.

Function Documentation

netStatus arp_cache_ip	(	uint32_t	if_num,
		const uint8_t *	ip_addr,
		arpCacheType	type
	)

Determine whether the ARP table has MAC address resolved for requested IP address.

Parameters

[in]	if_num	interface number.
[in]	ip_addr	requested IP address.
[in]	type	address cache type

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function arp_cache_ip determines whether the ARP table has a MAC (Ethernet) address entry for the requested IP address. If an entry does not exist, the function forces the Network Core to resolve and cache the MAC address into the internal ARP table buffer. To resolve the MAC address, the Network Core sends an ARP request to the network.

The argument if_num is the Ethernet interface number for which to check the ARP table.

The argument ip_addr points to a buffer containing the four octets of the dotted decimal IP address to be resolved.

The argument type specifies whether the IP address is fixed or temporary. This consequently determines whether or not the Network Core automatically refreshes the IP address entry in the ARP cache.

Type	Description
arpCacheTemporaryIP	The IP address is temporary, and thus Network removes the IP address entry from the ARP cache after a timeout.
arpCacheFixedIP	The IP address is fixed, and thus Network's ARP module automatically refreshes the IP address entry after the timeout.

Note

Only the Ethernet interface uses the arp_cache_ip function. There is no ARP protocol for the PPP or SLIP interface.
The arp_cache_ip function is primarily useful before sending the first UDP packet. The function is not necessary before sending TCP packets because the TCP module can retransmit the packet if the remote machine did not receive the packet.

Code Example

bool ip_cached;
void send_data (void) {
  static const uint8_t rem_IP[4] = {192,168,0,100};
  if (ip_cached == __FALSE) {
    if (arp_cache_ip (0, rem_IP, arpCacheFixedIP) == __FALSE) {
      // Wait, 'rem_IP' address not resolved yet. 
      return;
    }
    ip_cached == __TRUE;
  }
   ..
  // OK send UDP data packet here. 
   ..
}
void main (void) {
  // Initialize the Network Core 
  net_initialize ();
  ip_cached = __FALSE;
  while (1) {
    timer_poll ();
    // Run main Network Core 'thread' 
    net_main ();
    send_data ();
  }
}

netStatus arp_cache_mac	(	uint32_t	if_num,
		const uint8_t *	mac_addr
	)

Determine whether the ARP table has IP address resolved for requested MAC address.

Parameters

[in]	if_num	interface number.
[in]	mac_addr	requested MAC address.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function arp_cache_mac determines whether the ARP table has an IP address entry for the requested MAC (Ethernet) address mac_addr. If an entry does not exist, the function forces the Network Core to resolve and cache the IP address into the internal ARP table buffer. To resolve the IP address, the Network Core sends an inverse ARP request to the network.

The argument if_num is the Ethernet interface number for which to check the ARP table.

The argument mac_addr points to a buffer containing the six octets of the MAC address to be resolved.

Note: Only the Ethernet interface uses the arp_cache_mac function. There is no ARP protocol for the PPP or SLIP interface.

Code Example

// coming soon

netStatus arp_get_ip	(	const uint8_t *	mac_addr,
		uint8_t *	ip_addr
	)

Get IP address from the ARP cache.

Parameters

[in]	mac_addr	requested MAC address.
[out]	ip_addr	resolved IP address.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function arp_get_ip determines the resolved IP address for a specific MAC address.

The argument mac_addr points to a buffer containing the six octets of the MAC address to be resolved.

The out argument ip_addr points to a buffer containing the resolved IP address.

Refer to

arp_cache_mac to enforce the Network Core to resolve the MAC address.
arp_get_mac to get the resolved MAC address.

Code Example

//coming soon

netStatus arp_get_mac	(	const uint8_t *	ip_addr,
		uint8_t *	mac_addr
	)

Get MAC address from the ARP cache.

Parameters

[in]	ip_addr	requested IP address.
[out]	mac_addr	resolved MAC address.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function arp_get_mac determines the resolved MAC address for a specific IP address.

The argument ip_addr points to a buffer containing the IP address.

The out argument mac_addr points to a buffer containing the resolved six octets of the MAC address.

Refer to

arp_cache_ip to enforce the Network Core to resolve the IP address.
arp_get_ip to retrieve the resolved IP address.

Code Example

//coming soon

void dhcp_client_notify	(	uint32_t	if_num,
		dhcpClientOption	opt,
		const uint8_t *	val,
		uint32_t	len
	)

Notify the user of DHCP event or extended DHCP option.

Parameters

[in]	if_num	interface number.
[in]	opt	DHCP option as defined in dhcpClientOption.
[in]	val	pointer to the option value.
[in]	len	length of the option value in bytes.

Returns: none.

The function dhcp_client_notify is called by the DHCP client when the extended DHCP options are enabled in the system configuration. This function is used to notify the user about extended DHCP option values. If this function is not provided in the user code, DHCP client notifications are not possible.

The argument if_num specifies the Ethernet interface for which DHCP is to be used.

The argument opt specifies the extended DHCP option code, as defined in dhcpClientOption enum:

Option	Event	Description
0	dhcpClientIPaddress	IP address change event.
42	dhcpClientNTPservers	Pointer to an array of NTP Server IP addresses.
67	dhcpClientBootfileName	Pointer to a 0-terminated boot file name.

The argument val is a pointer to the option value.

The argument len is specifying the length of the option value in bytes.

Note: This function is optional. It is not needed for a default DHCP client configuration.

Code Example

// IP address change notification
void dhcp_client_notify (uint32_t if_num, dhcpClientOption opt, const uint8_t *val, uint32_t len) {
  if (opt == dhcpClientIPaddress)
    { // IP address has changed
    sprintf (lcd_text[0],"IP address:");
    sprintf (lcd_text[1],"%d.%d.%d.%d", val[0], val[1], val[2], val[3]);
    LCDupdate = true;
  }
}

netStatus dhcp_disable ( uint32_t if_num )

Disable Dynamic Host Configuration at runtime.

Parameters

[in] if_num interface number.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function dhcp_disable permanently disables the Dynamic Host Configuration at runtime. To enable the DHCP client again, you must restart the system.

The argument if_num specifies the Ethernet interface for which DHCP is to be disabled.

Note: You can use the function only when the Dynamic Host Configuration is enabled in the Net_Config_ETH_n.c configuration file.

Code Example

void main (void) {
  // Initialize the Network Core 
  net_initialize ();
  if (DHCP_mode == 0) {
    dhcp_disable (0);
  }
  while (1) {
    // Run main Network Core 'thread'
    net_main ();
  }
}

void eth_link_notify	(	uint32_t	if_num,
		ethLinkEvent	event
	)

Notify the user of Ethernet link state change event.

Parameters

[in]	if_num	interface number.
[in]	event	Ethernet link state event as defined in ethLinkEvent.

Returns: none.

The function eth_link_notify polls the PHY status and notifies the user about link state changes.

The argument if_num specifies the Ethernet interface for which is to be checked.

The argument event specifies link event, as defined in ethLinkEvent enum:

Event	Description
ethLinkDown	Link down.
ethLinkUp_10MHalfDuplex	Link up (10 MBit half duplex).
ethLinkUp_10MFullDuplex	Link up (10 MBit full duplex).
ethLinkUp_100MHalfDuplex	Link up (100 MBit half duplex).
ethLinkUp_100MFullDuplex	Link up (100 MBit full duplex).
ethLinkUp_1GHalfDuplex	Link up (1 GBit half duplex).
ethLinkUp_1GFullDuplex	Link up (1 GBit full duplex).

netStatus icmp_ping	(	const uint8_t *	ip_addr,
		net_icmp_cb_t	cb_func
	)

Start ICMP ping process.

Parameters

[in]	ip_addr	IP address of the remote host.
[in]	cb_func	callback function to call, when ping session ends.

Returns: status code that indicates the execution status of the function as defined with netStatus.

The function icmp_ping starts the ICMP ping process on the Network Core. This causes the ICMP client to send the ICMP Echo request to remote IP address and waits for an ICMP Echo reply.

The argument ip_addr points to an array of 4 bytes containing the dotted-decimal notation of the IP address of the remote host to be pinged.

The argument cb_func points to an event callback function called by the ICMP client (running on Network Core) when the ping session ends. Refer to net_icmp_cb_t.

Code Example

static void ping_cback (icmpEvent event);
 
void ping_host (void) {
  uint8_t hostip[4] = {192,168,0,100};
 
  if (icmp_ping (&hostip[0], ping_cback) == netOK) {
    printf("Ping started.\n");
  }
  else {
    printf("Ping not started, ICMP not ready or bad parameters.\n");
  }
}
 
static void ping_cback (icmpEvent event) {
  switch (event) {
    case icmpEventSuccess:
      printf ("Remote host responded to ping.\n");
      break;
    case icmpEventTimeout:
      printf ("Ping timeout, no response.\n");
      break;
  }
}

Typedefs

Enumerations

Functions

Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation