Functions of the Ethernet Interface. More...

Functions
netStatus	netETH_SendRaw (uint32_t if_num, const uint8_t *buf, uint32_t len)
	Send raw Ethernet data. [thread-safe].

Description

Functions of the Ethernet Interface.

In the Network Component, the Ethernet interface API is responsible for various Application/Internet/Link layer protocols such as ARP, NDP, IGMP, MLD and DHCP. In the Network Component, these protocols are supported for IPv4 and IPv6 connections (where applicable).

To get or set Ethernet options, use the generic netIF_GetOption and netIF_SetOption. The available options are as follows:

Option	Description
netIF_OptionMAC_Address	Ethernet MAC Address
netIF_OptionVLAN_Identifier	Ethernet VLAN Identifier
netIF_OptionIP4_MTU	IPv4 Maximum Transmission Unit
netIF_OptionIP4_Address	IPv4 Address
netIF_OptionIP4_SubnetMask	IPv4 Subnet mask
netIF_OptionIP4_DefaultGateway	IPv4 Default Gateway
netIF_OptionIP4_PrimaryDNS	IPv4 Primary DNS
netIF_OptionIP4_SecondaryDNS	IPv4 Secondary DNS
netIF_OptionIP6_MTU	IPv6 Maximum Transmission Unit
netIF_OptionIP6_LinkLocalAddress	IPv6 Link-local Address
netIF_OptionIP6_StaticAddress	IPv6 Static Address
netIF_OptionIP6_DynamicAddress	IPv6 Dynamic Address
netIF_OptionIP6_SubnetPrefixLength	IPv6 Subnet Prefix-length
netIF_OptionIP6_DefaultGateway	IPv6 Default Gateway
netIF_OptionIP6_PrimaryDNS	IPv6 Primary DNS
netIF_OptionIP6_SecondaryDNS	IPv6 Secondary DNS

The callback function netETH_Notify informs the user application about state changes on the Ethernet link.

Address Resolution Protocol (ARP, IPv4 only)

The Address Resolution Protocol (ARP) is used to resolve network layer (IP) addresses to link layer (MAC) addresses. It is being used in IPv4 networks only. In IPv6 networks, Neighbor Discovery Protocol (NDP) is used instead.

The Network Component provides five functions for ARP. Two functions are working on the ARP table, two functions actually resolve the IP or MAC address and one function that checks whether the IP address is already in use. netARP_CacheIP determines whether the ARP table has a MAC address resolved for a certain IP address. netARP_CacheMAC determines whether the ARP table has an IP address resolved for a certain MAC address. To retrieve the MAC address for an IP address from the ARP table, use netARP_GetMAC, while netARP_GetIP provides the IP address for a given MAC address. To verify that the IP address is not used in local area network, use netARP_Probe.

Neighbor Discovery Protocol (NDP, IPv6 only)

The Neighbor Discovery Protocol (NDP) operates on the link layer and is responsible for

address auto-configuration of a node
discovery of other nodes on the link
determining the link layer (MAC) addresses of other nodes
duplicate address detection
finding available routers and Domain Name System (DNS) servers
address prefix discovery and
maintaining trace information to other neighboring nodes.

It is available for IPv6 only.

The function netNDP_CacheIP checks if the NDP table has a MAC address resolved for a certain IPv6 address. To retrieve this MAC address, use netNDP_GetMAC. To retrieve an IPv6 address for any given MAC address, use netNDP_GetIP. To verify that the IPv6 address is not used in local area network, use netNDP_Probe.

Internet Group Management Protocol (IGMP, IPv4 only)

The Internet Group Management Protocol (IGMP) is used to operate IP Multicasting. This means that an IP datagram is sent to a "host group". A multicast datagram is delivered to all members of its target host group. The IGMPv1 and IGMPv2 protocol specification is supported by the Network Component. It is only available for IPv4.

To add a host to a specific host group, use netIGMP_Join. To leave a host group, netIGMP_Leave is used.

Multicast Listener Discovery Protocol (MLD, IPv6 only)

The Multicast Listener Discovery (MLD) is used to perform IPv6 Multicasting. This means that an IPv6 datagram is sent to a "multicast group". A multicast datagram is delivered to all members of its destination multicast listening nodes. The MLDv1 protocol specification is supported by the Network Component. It is only available for IPv6.

To add a node to a specific multicast group, use netMLD_Join. To leave a multicast group, netMLD_Leave is used.

Dynamic Host Configuration Protocol (DHCP, IPv4 only)

The Dynamic Host Configuration Protocol (DHCP) is used for dynamically distributing network configuration parameters, such as IP addresses for interfaces and services. Using DHCP, network nodes request IP addresses and networking parameters automatically from a DHCP server, eliminating the need to configure these settings manually (refer to IP Address Assignment for more information). Although DHCP is specified for IPv4 and IPv6 networks, the Network Component is only supporting IPv4 networks at the moment.

Like all services, the DHCP is normally started automatically if NET_START_SERVICE is set to 1 in the Net_Config.h configuration file. If it is disabled, DHCP needs to be started manually in the user application using netDHCP_Enable. At runtime, it is always possible to stop DHCP using the function netDHCP_Disable. In this case, the Network Core will revert the IP address of the node to the static IP address specified in the Net_Config_ETH_n.h file.

The callback function netDHCP_Notify notifies the user application of DHCP events or extended DHCP options. This function is optional and not required for a default DHCP client configuration. However, if your application requires the ability to react on changes of the IP address, you need to implement this function in the user code.

Function Documentation

◆ netETH_SendRaw()

netStatus netETH_SendRaw	(	uint32_t	if_num,
		const uint8_t *	buf,
		uint32_t	len
	)

Send raw Ethernet data. [thread-safe].

Parameters

[in]	if_num	Ethernet interface number.
[in]	buf	buffer containing the data.
[in]	len	length of data in bytes.

Returns: status code that indicates the execution status of the function.

The function netETH_SendRaw sends the raw Ethernet data to a remote machine. The data must contain Ethernet header and payload data. This allows the users to implement additional Ethernet protocols, which are not supported by the network library.

The argument if_num specifies the Ethernet Interface which is used for sending.

The argument buf points to a buffer containing Ethernet raw data.

The argument len specifies the number of data bytes to send.

Possible netStatus return values:

netOK: Data sent successfully.
netInvalidParameter: Invalid parameter provided.
netWrongState: Ethernet link is down.
netDriverError: Ethernet driver internal error.
netBusy: Ethernet transmitter is busy.

Code Example

void netETH_ReceiveRaw (uint32_t if_num, const uint8_t *buf, uint32_t len) {
  uint8_t echo_buf[60];
 
  // Echo small packets
  if (len <= 60) {
    memcpy (&echo_buf[0], &buf[6], 6);          // Destination MAC address
    memcpy (&echo_buf[6], &buf[0], 6);          // Source MAC address
    memcpy (&echo_buf[12], &buf[12], len-12);   // EtherType + data
    netETH_SendRaw (if_num, echo_buf, len);
  }
}