Ethernet¶
Overview¶
ESP-IDF provides a set of consistent and flexible APIs to support both internal Ethernet MAC (EMAC) controller and external SPI-Ethernet modules.
This programming guide is split into the following sections:
Basic Ethernet Concepts¶
Ethernet is an asynchronous Carrier Sense Multiple Access with Collision Detect (CSMA/CD) protocol/interface. It is generally not well suited for low power applications. However, with ubiquitous deployment, internet connectivity, high data rates and limitless rage expandability, Ethernet can accommodate nearly all wired communications.
Normal IEEE 802.3 compliant Ethernet frames are between 64 and 1518 bytes in length. They are made up of five or six different fields: a destination MAC address (DA), a source MAC address (SA), a type/length field, data payload, an optional padding field and a Cyclic Redundancy Check (CRC). Additionally, when transmitted on the Ethernet medium, a 7-byte preamble field and Start-of-Frame (SOF) delimiter byte are appended to the beginning of the Ethernet packet.
Thus the traffic on the twist-pair cabling will appear as shown blow:
Preamble and Start-of-Frame Delimiter¶
The preamble contains seven bytes of 55H
, it allows the receiver to lock onto the stream of data before the actual frame arrives.
The Start-of-Frame Delimiter (SFD) is a binary sequence 10101011
(as seen on the physical medium). It is sometimes considered to be part of the preamble.
When transmitting and receiving data, the preamble and SFD bytes will automatically be generated or stripped from the packets.
Destination Address¶
The destination address field contains a 6-byte length MAC address of the device that the packet is directed to. If the Least Significant bit in the first byte of the MAC address is set, the address is a multi-cast destination. For example, 01-00-00-00-F0-00 and 33-45-67-89-AB-CD are multi-cast addresses, while 00-00-00-00-F0-00 and 32-45-67-89-AB-CD are not. Packets with multi-cast destination addresses are designed to arrive and be important to a selected group of Ethernet nodes. If the destination address field is the reserved multi-cast address, i.e. FF-FF-FF-FF-FF-FF, the packet is a broadcast packet and it will be directed to everyone sharing the network. If the Least Significant bit in the first byte of the MAC address is clear, the address is a uni-cast address and will be designed for usage by only the addressed node.
Normally the EMAC controller incorporates receive filters which can be used to discard or accept packets with multi-cast, broadcast and/or uni-cast destination addresses. When transmitting packets, the host controller is responsible for writing the desired destination address into the transmit buffer.
Source Address¶
The source address field contains a 6-byte length MAC address of the node which created the Ethernet packet. Users of Ethernet must generate a unique MAC address for each controller used. MAC addresses consist of two portions. The first three bytes are known as the Organizationally Unique Identifier (OUI). OUIs are distributed by the IEEE. The last three bytes are address bytes at the discretion of the company that purchased the OUI. More information about MAC Address used in ESP-IDF, please see MAC Address Allocation.
When transmitting packets, the assigned source MAC address must be written into the transmit buffer by the host controller.
Type / Length¶
The type/length field is a 2-byte field, if the value in this field is <= 1500 (decimal), it is considered a length field and it specifies the amount of non-padding data which follows in the data field. If the value is >= 1536, it represents the protocol the following packet data belongs to. The following are the most common type values:
IPv4 = 0800H
IPv6 = 86DDH
ARP = 0806H
Users implementing proprietary networks may choose to treat this field as a length field, while applications implementing protocols such as the Internet Protocol (IP) or Address Resolution Protocol (ARP), should program this field with the appropriate type defined by the protocol’s specification when transmitting packets.
Payload¶
The payload field is a variable length field, anywhere from 0 to 1500 bytes. Larger data packets will violate Ethernet standards and will be dropped by most Ethernet nodes. This field contains the client data, such as an IP datagram.
Padding and FCS¶
The padding field is a variable length field added to meet IEEE 802.3 specification requirements when small data payloads are used. The DA, SA, type, payload and padding of an Ethernet packet must be no smaller than 60 bytes. Adding the required 4-byte FCS field, packets must be no smaller than 64 bytes. If the data field is less than 46 bytes long, a padding field is required.
The FCS field is a 4-byte field which contains an industry standard 32-bit CRC calculated with the data from the DA, SA, type, payload and padding fields. Given the complexity of calculating a CRC, the hardware normally will automatically generate a valid CRC and transmit it. Otherwise, the host controller must generate the CRC and place it in the transmit buffer.
Normally, the host controller does not need to concern itself with padding and the CRC which the hardware EMAC will also be able to automatically generate when transmitting and verify when receiving. However, the padding and CRC fields will be written into the receive buffer when packets arrive, so they may be evaluated by the host controller if needed.
Note
Besides the basic data frame described above, there’re two other common frame types in 10/100 Mbps Ethernet: control frames and VLAN tagged frames. They’re not supported in ESP-IDF.
Configure MAC and PHY¶
Ethernet driver is composed of two parts: MAC and PHY. The communication between MAC and PHY can have diverse choices: MII (Media Independent Interface), RMII (Reduced Media Independent Interface) and etc.
One of the obvious difference between MII and RMII is the signal consumption. For MII, it usually costs up to 18 signals. Instead, RMII interface can reduce the consumption to 9.
In RMII mode, both the receiver and transmitter signals are referenced to the REF_CLK
. REF_CLK must be stable during any access to PHY and MAC.
Generally there’re three ways to generate the REF_CLK
depending on the PHY device in your design:
Some PHY chip can derive the
REF_CLK
from its external connected 25MHz crystal oscillator (as seen the option a in the picture). In this case, you should selectCONFIG_ETH_RMII_CLK_INPUT
in CONFIG_ETH_RMII_CLK_MODE.Some PHY chip uses an external connected 50MHz crystal oscillator or other clock source, which can also be used as the
REF_CLK
for MAC side (as seen the option b in the picture). In this case, you still need to selectCONFIG_ETH_RMII_CLK_INPUT
in CONFIG_ETH_RMII_CLK_MODE.Some EMAC controller can generate the
REF_CLK
using its internal high precision PLL (as seen the option c in the picture). In this case, you should selectCONFIG_ETH_RMII_CLK_OUTPUT
in CONFIG_ETH_RMII_CLK_MODE.
Warning
If the RMII clock mode is selected to CONFIG_ETH_RMII_CLK_OUTPUT
, then GPIO0
can be used to output the REF_CLK
signal. See CONFIG_ETH_RMII_CLK_OUTPUT_GPIO0 for more information.
What’s more, if you’re not using PSRAM in your design, GPIO16 and GPIO17 are also available to output the reference clock. See CONFIG_ETH_RMII_CLK_OUT_GPIO for more information.
If the RMII clock mode is selected to CONFIG_ETH_RMII_CLK_INPUT
, then GPIO0
is the only choice to input the REF_CLK
signal.
Please note that, GPIO0
is also an important strapping GPIO on ESP32.
If GPIO0 samples a low level during power up, ESP32 will go into download mode. The system will get halted until a manually reset.
The workaround of this issue is disabling the REF_CLK
in hardware by default, so that the strapping pin won’t be interfered by other signals in boot stage. Then re-enable the REF_CLK
in Ethernet driver installation stage.
The ways to disable the REF_CLK
signal can be:
Disable or power down the crystal oscillator (as the case b in the picture).
Force the PHY device in reset status (as the case a in the picture). This could fail for some PHY device (i.e. it still outputs signal to GPIO0 even in reset state).
No matter which RMII clock mode you select, you really need to take care of the signal integrity of REF_CLK in your hardware design! Keep the trace as short as possible. Keep it away from RF devices. Keep it away from inductor elements.
Note
ESP-IDF only supports the RMII interface (i.e. always select CONFIG_ETH_PHY_INTERFACE_RMII
in Kconfig option CONFIG_ETH_PHY_INTERFACE).
Signals used in data plane are fixed to specific GPIOs via MUX, they can’t be modified to other GPIOs. Signals used in control plane can be routed to any free GPIOs via Matrix. Please refer to ESP32-Ethernet-Kit for hardware design example.
We need to setup necessary parameters for MAC and PHY respectively based on your Ethernet board design and then combine the two together, completing the driver installation.
Configuration for MAC is described in eth_mac_config_t
, including:
sw_reset_timeout_ms
: software reset timeout value, in milliseconds, typically MAC reset should be finished within 100ms.rx_task_stack_size
andrx_task_prio
: the MAC driver creates a dedicated task to process incoming packets, these two parameters are used to set the stack size and priority of the task.smi_mdc_gpio_num
andsmi_mdio_gpio_num
: the GPIO number used to connect the SMI signals.flags
: specifying extra features that the MAC driver should have, it could be useful in some special situations. The value of this field can be OR’d with macros prefixed withETH_MAC_FLAG_
. For example, if the MAC driver should work when cache is disabled, then you should configure this field withETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE
.
Configuration for PHY is described in eth_phy_config_t
, including:
phy_addr
: multiple PHY device can share the same SMI bus, so each PHY needs a unique address. Usually this address is configured during hardware design by pulling up/down some PHY strapping pins. You can set the value from 0 to 15 based on your Ethernet board. Especially, if the SMI bus is shared by only one PHY device, setting this value to -1 can enable the driver to detect the PHY address automatically.reset_timeout_ms
: reset timeout value, in milliseconds, typically PHY reset should be finished within 100ms.autonego_timeout_ms
: auto-negotiation timeout value, in milliseconds. Ethernet driver will start negotiation with the peer Ethernet node automatically, to determine to duplex and speed mode. This value usually depends on the ability of the PHY device on your board.reset_gpio_num
: if your board also connect the PHY reset pin to one of the GPIO, then set it here. Otherwise, set this field to -1.
ESP-IDF provides a default configuration for MAC and PHY in macro ETH_MAC_DEFAULT_CONFIG
and ETH_PHY_DEFAULT_CONFIG
.
Create MAC and PHY Instance¶
Ethernet driver is implemented in an Object-Oriented style. Any operation on MAC and PHY should be based on the instance of them two.
eth_mac_config_t mac_config = ETH_MAC_DEFAULT_CONFIG(); // apply default MAC configuration
mac_config.smi_mdc_gpio_num = 23; // alter the GPIO used for MDC signal
mac_config.smi_mdio_gpio_num = 18; // alter the GPIO used for MDIO signal
esp_eth_mac_t *mac = esp_eth_mac_new_esp32(&mac_config); // create MAC instance
eth_phy_config_t phy_config = ETH_PHY_DEFAULT_CONFIG(); // apply default PHY configuration
phy_config.phy_addr = 1; // alter the PHY address according to your board design
phy_config.reset_gpio_num = 5; // alter the GPIO used for PHY reset
esp_eth_phy_t *phy = esp_eth_phy_new_ip101(&phy_config); // create PHY instance
// ESP-IDF officially supports several different Ethernet PHY
// esp_eth_phy_t *phy = esp_eth_phy_new_rtl8201(&phy_config);
// esp_eth_phy_t *phy = esp_eth_phy_new_lan8720(&phy_config);
// esp_eth_phy_t *phy = esp_eth_phy_new_dp83848(&phy_config);
Note
Care should be taken, when creating MAC and PHY instance for SPI-Ethernet modules (e.g. DM9051), the constructor function must have the same suffix (e.g. esp_eth_mac_new_dm9051 and esp_eth_phy_new_dm9051). This is because we don’t have other choices but the integrated PHY. Besides that, we have to create an SPI device handle firstly and then pass it to the MAC constructor function. More instructions on creating SPI device handle, please refer to SPI Master.
Install Driver¶
Ethernet driver also includes event-driven model, which will send useful and important event to user space. We need to initialize the event loop before installing the Ethernet driver. For more information about event-driven programming, please refer to ESP Event.
/** Event handler for Ethernet events */
static void eth_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data)
{
uint8_t mac_addr[6] = {0};
/* we can get the ethernet driver handle from event data */
esp_eth_handle_t eth_handle = *(esp_eth_handle_t *)event_data;
switch (event_id) {
case ETHERNET_EVENT_CONNECTED:
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr);
ESP_LOGI(TAG, "Ethernet Link Up");
ESP_LOGI(TAG, "Ethernet HW Addr %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_addr[4], mac_addr[5]);
break;
case ETHERNET_EVENT_DISCONNECTED:
ESP_LOGI(TAG, "Ethernet Link Down");
break;
case ETHERNET_EVENT_START:
ESP_LOGI(TAG, "Ethernet Started");
break;
case ETHERNET_EVENT_STOP:
ESP_LOGI(TAG, "Ethernet Stopped");
break;
default:
break;
}
}
esp_event_loop_create_default(); // create a default event loop that running in background
esp_event_handler_register(ETH_EVENT, ESP_EVENT_ANY_ID, ð_event_handler, NULL); // register Ethernet event handler (to deal with user specific stuffs when event like link up/down happened)
To install the Ethernet driver, we need to combine the instance of MAC and PHY and set some additional high-level configurations (i.e. not specific to either MAC or PHY) in esp_eth_config_t
:
mac
: instance that created from MAC generator (e.g.esp_eth_mac_new_esp32()
).phy
: instance that created from PHY generator (e.g.esp_eth_phy_new_ip101()
).check_link_period_ms
: Ethernet driver starts an OS timer to check the link status periodically, this field is used to set the interval, in milliseconds.stack_input
: In most of Ethernet IoT applications, any Ethernet frame that received by driver should be passed to upper layer (e.g. TCP/IP stack). This field is set to a function which is responsible to deal with the incoming frames. You can even update this field at runtime via functionesp_eth_update_input_path()
after driver installation.on_lowlevel_init_done
andon_lowlevel_deinit_done
: These two fields are used to specify the hooks which get invoked when low level hardware has been initialized or de-initialized.
ESP-IDF provides a default configuration for driver installation in macro ETH_DEFAULT_CONFIG
.
esp_eth_config_t config = ETH_DEFAULT_CONFIG(mac, phy); // apply default driver configuration
esp_eth_handle_t eth_handle = NULL; // after driver installed, we will get the handle of the driver
esp_eth_driver_install(&config, ð_handle); // install driver
Start Ethernet Driver¶
After driver installation, we can start Ethernet immediately.
esp_eth_start(eth_handle); // start Ethernet driver state machine
Connect Driver to TCP/IP Stack¶
Up until now, we have installed the Ethernet driver. From the view of OSI (Open System Interconnection), we’re still on level 2 (i.e. Data Link Layer). We can detect link up and down event, we can gain MAC address in user space, but we can’t obtain IP address, let alone send HTTP request. The TCP/IP stack used in ESP-IDF is called LwIP, for more information about it, please refer to LwIP.
To connect Ethernet driver to TCP/IP stack, these three steps need to follow:
Create network interface for Ethernet driver
Register IP event handlers
Attach the network interface to Ethernet driver
More information about network interface, please refer to Network Interface.
/** Event handler for IP_EVENT_ETH_GOT_IP */
static void got_ip_event_handler(void *arg, esp_event_base_t event_base,
int32_t event_id, void *event_data)
{
ip_event_got_ip_t *event = (ip_event_got_ip_t *) event_data;
const esp_netif_ip_info_t *ip_info = &event->ip_info;
ESP_LOGI(TAG, "Ethernet Got IP Address");
ESP_LOGI(TAG, "~~~~~~~~~~~");
ESP_LOGI(TAG, "ETHIP:" IPSTR, IP2STR(&ip_info->ip));
ESP_LOGI(TAG, "ETHMASK:" IPSTR, IP2STR(&ip_info->netmask));
ESP_LOGI(TAG, "ETHGW:" IPSTR, IP2STR(&ip_info->gw));
ESP_LOGI(TAG, "~~~~~~~~~~~");
}
esp_netif_init()); // Initialize TCP/IP network interface (should be called only once in application)
esp_netif_config_t cfg = ESP_NETIF_DEFAULT_ETH(); // apply default network interface configuration for Ethernet
esp_netif_t *eth_netif = esp_netif_new(&cfg); // create network interface for Ethernet driver
esp_eth_set_default_handlers(eth_netif); // set default handlers to process TCP/IP stuffs
esp_event_handler_register(IP_EVENT, IP_EVENT_ETH_GOT_IP, &got_ip_event_handler, NULL); // register user defined IP event handlers
esp_netif_attach(eth_netif, esp_eth_new_netif_glue(eth_handle)); // attach Ethernet driver to TCP/IP stack
esp_eth_start(eth_handle); // start Ethernet driver state machine
Warning
User’s Ethernet/IP event handlers need to be registered after registration of default handlers (i.e. after esp_eth_set_default_handlers()
). General recommendation is to fully initialize Ethernet driver and network interface prior registering user’s Ethernet/IP event handlers, i.e. register the user event handlers as the last thing prior starting the Ethernet driver. Such approach ensures that Ethernet/IP events get executed first by the Ethernet driver or network interface and so the system is in expected state when executing user’s handlers.
Misc control of Ethernet driver¶
The following functions should only be invoked after the Ethernet driver has been installed.
Stop Ethernet driver:
esp_eth_stop()
Update Ethernet data input path:
esp_eth_update_input_path()
Misc get/set of Ethernet driver attributes:
esp_eth_ioctl()
/* get MAC address */
uint8_t mac_addr[6];
memset(mac_addr, 0, sizeof(mac_addr));
esp_eth_ioctl(eth_handle, ETH_CMD_G_MAC_ADDR, mac_addr);
ESP_LOGI(TAG, "Ethernet MAC Address: %02x:%02x:%02x:%02x:%02x:%02x",
mac_addr[0], mac_addr[1], mac_addr[2], mac_addr[3], mac_addr[4], mac_addr[5]);
/* get PHY address */
int phy_addr = -1;
esp_eth_ioctl(eth_handle, ETH_CMD_G_PHY_ADDR, &phy_addr);
ESP_LOGI(TAG, "Ethernet PHY Address: %d", phy_addr);
Flow control¶
Ethernet on MCU usually has a limitation in the number of frames it can handle during network congestion, because of the limitation in RAM size. A sending station might be transmitting data faster than the peer end can accept it. Ethernet flow control mechanism allows the receiving node to signal the sender requesting suspension of transmissions until the receiver catches up. The magic behind that is the pause frame, which was defined in IEEE 802.3x.
Pause frame is a special Ethernet frame used to carry the pause command, whose EtherType field is 0x8808, with the Control opcode set to 0x0001. Only stations configured for full-duplex operation may send pause frames. When a station wishes to pause the other end of a link, it sends a pause frame to the 48-bit reserved multicast address of 01-80-C2-00-00-01. The pause frame also includes the period of pause time being requested, in the form of a two-byte integer, ranging from 0 to 65535.
After Ethernet driver installation, the flow control feature is disabled by default. You can enable it by invoking esp_eth_ioctl(eth_handle, ETH_CMD_S_FLOW_CTRL, true);. One thing should be kept in mind, is that the pause frame ability will be advertised to peer end by PHY during auto negotiation. Ethernet driver sends pause frame only when both sides of the link support it.
Application Example¶
Ethernet basic example: ethernet/basic.
Ethernet iperf example: ethernet/iperf.
Ethernet to Wi-Fi AP “router”: ethernet/eth2ap.
Most of protocol examples should also work for Ethernet: protocols.
API Reference¶
Header File¶
Functions¶
-
esp_err_t
esp_eth_driver_install
(const esp_eth_config_t *config, esp_eth_handle_t *out_hdl)¶ Install Ethernet driver.
- Return
ESP_OK: install esp_eth driver successfully
ESP_ERR_INVALID_ARG: install esp_eth driver failed because of some invalid argument
ESP_ERR_NO_MEM: install esp_eth driver failed because there’s no memory for driver
ESP_FAIL: install esp_eth driver failed because some other error occurred
- Parameters
[in] config
: configuration of the Ethernet driver[out] out_hdl
: handle of Ethernet driver
-
esp_err_t
esp_eth_driver_uninstall
(esp_eth_handle_t hdl)¶ Uninstall Ethernet driver.
- Note
It’s not recommended to uninstall Ethernet driver unless it won’t get used any more in application code. To uninstall Ethernet driver, you have to make sure, all references to the driver are released. Ethernet driver can only be uninstalled successfully when reference counter equals to one.
- Return
ESP_OK: uninstall esp_eth driver successfully
ESP_ERR_INVALID_ARG: uninstall esp_eth driver failed because of some invalid argument
ESP_ERR_INVALID_STATE: uninstall esp_eth driver failed because it has more than one reference
ESP_FAIL: uninstall esp_eth driver failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver
-
esp_err_t
esp_eth_start
(esp_eth_handle_t hdl)¶ Start Ethernet driver ONLY in standalone mode (i.e. without TCP/IP stack)
- Note
This API will start driver state machine and internal software timer (for checking link status).
- Return
ESP_OK: start esp_eth driver successfully
ESP_ERR_INVALID_ARG: start esp_eth driver failed because of some invalid argument
ESP_ERR_INVALID_STATE: start esp_eth driver failed because driver has started already
ESP_FAIL: start esp_eth driver failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver
-
esp_err_t
esp_eth_stop
(esp_eth_handle_t hdl)¶ Stop Ethernet driver.
- Note
This function does the oppsite operation of
esp_eth_start
.- Return
ESP_OK: stop esp_eth driver successfully
ESP_ERR_INVALID_ARG: stop esp_eth driver failed because of some invalid argument
ESP_ERR_INVALID_STATE: stop esp_eth driver failed because driver has not started yet
ESP_FAIL: stop esp_eth driver failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver
-
esp_err_t
esp_eth_update_input_path
(esp_eth_handle_t hdl, esp_err_t (*stack_input)(esp_eth_handle_t hdl, uint8_t *buffer, uint32_t length, void *priv), void *priv, )¶ Update Ethernet data input path (i.e. specify where to pass the input buffer)
- Note
After install driver, Ethernet still don’t know where to deliver the input buffer. In fact, this API registers a callback function which get invoked when Ethernet received new packets.
- Return
ESP_OK: update input path successfully
ESP_ERR_INVALID_ARG: update input path failed because of some invalid argument
ESP_FAIL: update input path failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver[in] stack_input
: function pointer, which does the actual process on incoming packets[in] priv
: private resource, which gets passed tostack_input
callback without any modification
-
esp_err_t
esp_eth_transmit
(esp_eth_handle_t hdl, void *buf, size_t length)¶ General Transmit.
- Return
ESP_OK: transmit frame buffer successfully
ESP_ERR_INVALID_ARG: transmit frame buffer failed because of some invalid argument
ESP_FAIL: transmit frame buffer failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver[in] buf
: buffer of the packet to transfer[in] length
: length of the buffer to transfer
-
esp_err_t
esp_eth_receive
(esp_eth_handle_t hdl, uint8_t *buf, uint32_t *length)¶ General Receive is deprecated and shall not be accessed from app code, as polling is not supported by Ethernet.
- Note
Before this function got invoked, the value of “length” should set by user, equals the size of buffer. After the function returned, the value of “length” means the real length of received data.
- Note
This API was exposed by accident, users should not use this API in their applications. Ethernet driver is interrupt driven, and doesn’t support polling mode. Instead, users should register input callback with
esp_eth_update_input_path
.- Return
ESP_OK: receive frame buffer successfully
ESP_ERR_INVALID_ARG: receive frame buffer failed because of some invalid argument
ESP_ERR_INVALID_SIZE: input buffer size is not enough to hold the incoming data. in this case, value of returned “length” indicates the real size of incoming data.
ESP_FAIL: receive frame buffer failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver[out] buf
: buffer to preserve the received packet[out] length
: length of the received packet
-
esp_err_t
esp_eth_ioctl
(esp_eth_handle_t hdl, esp_eth_io_cmd_t cmd, void *data)¶ Misc IO function of Etherent driver.
- Return
ESP_OK: process io command successfully
ESP_ERR_INVALID_ARG: process io command failed because of some invalid argument
ESP_FAIL: process io command failed because some other error occurred
- Parameters
[in] hdl
: handle of Ethernet driver[in] cmd
: IO control command[in] data
: specificed data for command
-
esp_err_t
esp_eth_increase_reference
(esp_eth_handle_t hdl)¶ Increase Ethernet driver reference.
- Note
Ethernet driver handle can be obtained by os timer, netif, etc. It’s dangerous when thread A is using Ethernet but thread B uninstall the driver. Using reference counter can prevent such risk, but care should be taken, when you obtain Ethernet driver, this API must be invoked so that the driver won’t be uninstalled during your using time.
- Return
ESP_OK: increase reference successfully
ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument
- Parameters
[in] hdl
: handle of Ethernet driver
-
esp_err_t
esp_eth_decrease_reference
(esp_eth_handle_t hdl)¶ Decrease Ethernet driver reference.
- Return
ESP_OK: increase reference successfully
ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument
- Parameters
[in] hdl
: handle of Ethernet driver
Structures¶
-
struct
esp_eth_config_t
¶ Configuration of Ethernet driver.
Public Members
-
esp_eth_mac_t *
mac
¶ Ethernet MAC object.
-
esp_eth_phy_t *
phy
¶ Ethernet PHY object.
-
uint32_t
check_link_period_ms
¶ Period time of checking Ethernet link status.
-
esp_err_t (*
stack_input
)(esp_eth_handle_t eth_handle, uint8_t *buffer, uint32_t length, void *priv)¶ Input frame buffer to user’s stack.
- Return
ESP_OK: input frame buffer to upper stack successfully
ESP_FAIL: error occurred when inputting buffer to upper stack
- Parameters
[in] eth_handle
: handle of Ethernet driver[in] buffer
: frame buffer that will get input to upper stack[in] length
: length of the frame buffer
-
esp_err_t (*
on_lowlevel_init_done
)(esp_eth_handle_t eth_handle)¶ Callback function invoked when lowlevel initialization is finished.
- Return
ESP_OK: process extra lowlevel initialization successfully
ESP_FAIL: error occurred when processing extra lowlevel initialization
- Parameters
[in] eth_handle
: handle of Ethernet driver
-
esp_err_t (*
on_lowlevel_deinit_done
)(esp_eth_handle_t eth_handle)¶ Callback function invoked when lowlevel deinitialization is finished.
- Return
ESP_OK: process extra lowlevel deinitialization successfully
ESP_FAIL: error occurred when processing extra lowlevel deinitialization
- Parameters
[in] eth_handle
: handle of Ethernet driver
-
esp_eth_mac_t *
Header File¶
Functions¶
-
esp_err_t
esp_eth_detect_phy_addr
(esp_eth_mediator_t *eth, int *detected_addr)¶ Detect PHY address.
- Return
ESP_OK: detect phy address successfully
ESP_ERR_INVALID_ARG: invalid parameter
ESP_ERR_NOT_FOUND: can’t detect any PHY device
ESP_FAIL: detect phy address failed because some error occurred
- Parameters
[in] eth
: mediator of Ethernet driver[out] detected_addr
: a valid address after detection
Structures¶
-
struct
esp_eth_mediator_s
¶ Ethernet mediator.
Public Members
-
esp_err_t (*
phy_reg_read
)(esp_eth_mediator_t *eth, uint32_t phy_addr, uint32_t phy_reg, uint32_t *reg_value)¶ Read PHY register.
- Return
ESP_OK: read PHY register successfully
ESP_FAIL: read PHY register failed because some error occurred
- Parameters
[in] eth
: mediator of Ethernet driver[in] phy_addr
: PHY Chip address (0~31)[in] phy_reg
: PHY register index code[out] reg_value
: PHY register value
-
esp_err_t (*
phy_reg_write
)(esp_eth_mediator_t *eth, uint32_t phy_addr, uint32_t phy_reg, uint32_t reg_value)¶ Write PHY register.
- Return
ESP_OK: write PHY register successfully
ESP_FAIL: write PHY register failed because some error occurred
- Parameters
[in] eth
: mediator of Ethernet driver[in] phy_addr
: PHY Chip address (0~31)[in] phy_reg
: PHY register index code[in] reg_value
: PHY register value
-
esp_err_t (*
stack_input
)(esp_eth_mediator_t *eth, uint8_t *buffer, uint32_t length)¶ Deliver packet to upper stack.
- Return
ESP_OK: deliver packet to upper stack successfully
ESP_FAIL: deliver packet failed because some error occurred
- Parameters
[in] eth
: mediator of Ethernet driver[in] buffer
: packet buffer[in] length
: length of the packet
-
esp_err_t (*
on_state_changed
)(esp_eth_mediator_t *eth, esp_eth_state_t state, void *args)¶ Callback on Ethernet state changed.
- Return
ESP_OK: process the new state successfully
ESP_FAIL: process the new state failed because some error occurred
- Parameters
[in] eth
: mediator of Ethernet driver[in] state
: new state[in] args
: optional argument for the new state
-
esp_err_t (*
Macros¶
-
ETH_MAX_PAYLOAD_LEN
¶ Maximum Ethernet payload size.
-
ETH_MIN_PAYLOAD_LEN
¶ Minimum Ethernet payload size.
-
ETH_HEADER_LEN
¶ Ethernet frame header size: Dest addr(6 Bytes) + Src addr(6 Bytes) + length/type(2 Bytes)
-
ETH_CRC_LEN
¶ Ethernet frame CRC length.
-
ETH_VLAN_TAG_LEN
¶ Optional 802.1q VLAN Tag length.
-
ETH_JUMBO_FRAME_PAYLOAD_LEN
¶ Jumbo frame payload size.
-
ETH_MAX_PACKET_SIZE
¶ Maximum frame size (1522 Bytes)
-
ETH_MIN_PACKET_SIZE
¶ Minimum frame size (64 Bytes)
Type Definitions¶
-
typedef struct esp_eth_mediator_s
esp_eth_mediator_t
¶ Ethernet mediator.
Enumerations¶
-
enum
esp_eth_state_t
¶ Ethernet driver state.
Values:
-
ETH_STATE_LLINIT
¶ Lowlevel init done
-
ETH_STATE_DEINIT
¶ Deinit done
-
ETH_STATE_LINK
¶ Link status changed
-
ETH_STATE_SPEED
¶ Speed updated
-
ETH_STATE_DUPLEX
¶ Duplex updated
-
ETH_STATE_PAUSE
¶ Pause ability updated
-
-
enum
esp_eth_io_cmd_t
¶ Command list for ioctl API.
Values:
-
ETH_CMD_G_MAC_ADDR
¶ Get MAC address
-
ETH_CMD_S_MAC_ADDR
¶ Set MAC address
-
ETH_CMD_G_PHY_ADDR
¶ Get PHY address
-
ETH_CMD_S_PHY_ADDR
¶ Set PHY address
-
ETH_CMD_G_SPEED
¶ Get Speed
-
ETH_CMD_S_PROMISCUOUS
¶ Set promiscuous mode
-
ETH_CMD_S_FLOW_CTRL
¶ Set flow control
-
ETH_CMD_G_DUPLEX_MODE
¶ Get Duplex mode
-
-
enum
eth_link_t
¶ Ethernet link status.
Values:
-
ETH_LINK_UP
¶ Ethernet link is up
-
ETH_LINK_DOWN
¶ Ethernet link is down
-
-
enum
eth_speed_t
¶ Ethernet speed.
Values:
-
ETH_SPEED_10M
¶ Ethernet speed is 10Mbps
-
ETH_SPEED_100M
¶ Ethernet speed is 100Mbps
-
Header File¶
Functions¶
-
esp_eth_mac_t *
esp_eth_mac_new_esp32
(const eth_mac_config_t *config)¶ Create ESP32 Ethernet MAC instance.
- Return
instance: create MAC instance successfully
NULL: create MAC instance failed because some error occurred
- Parameters
config
: Ethernet MAC configuration
Structures¶
-
struct
esp_eth_mac_s
¶ Ethernet MAC.
Public Members
-
esp_err_t (*
set_mediator
)(esp_eth_mac_t *mac, esp_eth_mediator_t *eth)¶ Set mediator for Ethernet MAC.
- Return
ESP_OK: set mediator for Ethernet MAC successfully
ESP_ERR_INVALID_ARG: set mediator for Ethernet MAC failed because of invalid argument
- Parameters
[in] mac
: Ethernet MAC instance[in] eth
: Ethernet mediator
-
esp_err_t (*
init
)(esp_eth_mac_t *mac)¶ Initialize Ethernet MAC.
- Return
ESP_OK: initialize Ethernet MAC successfully
ESP_ERR_TIMEOUT: initialize Ethernet MAC failed because of timeout
ESP_FAIL: initialize Ethernet MAC failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance
-
esp_err_t (*
deinit
)(esp_eth_mac_t *mac)¶ Deinitialize Ethernet MAC.
- Return
ESP_OK: deinitialize Ethernet MAC successfully
ESP_FAIL: deinitialize Ethernet MAC failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance
-
esp_err_t (*
start
)(esp_eth_mac_t *mac)¶ Start Ethernet MAC.
- Return
ESP_OK: start Ethernet MAC successfully
ESP_FAIL: start Ethernet MAC failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance
-
esp_err_t (*
stop
)(esp_eth_mac_t *mac)¶ Stop Ethernet MAC.
- Return
ESP_OK: stop Ethernet MAC successfully
ESP_FAIL: stop Ethernet MAC failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance
-
esp_err_t (*
transmit
)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t length)¶ Transmit packet from Ethernet MAC.
- Return
ESP_OK: transmit packet successfully
ESP_ERR_INVALID_ARG: transmit packet failed because of invalid argument
ESP_ERR_INVALID_STATE: transmit packet failed because of wrong state of MAC
ESP_FAIL: transmit packet failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] buf
: packet buffer to transmit[in] length
: length of packet
-
esp_err_t (*
receive
)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t *length)¶ Receive packet from Ethernet MAC.
- Note
Memory of buf is allocated in the Layer2, make sure it get free after process.
- Note
Before this function got invoked, the value of “length” should set by user, equals the size of buffer. After the function returned, the value of “length” means the real length of received data.
- Return
ESP_OK: receive packet successfully
ESP_ERR_INVALID_ARG: receive packet failed because of invalid argument
ESP_ERR_INVALID_SIZE: input buffer size is not enough to hold the incoming data. in this case, value of returned “length” indicates the real size of incoming data.
ESP_FAIL: receive packet failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[out] buf
: packet buffer which will preserve the received frame[out] length
: length of the received packet
-
esp_err_t (*
read_phy_reg
)(esp_eth_mac_t *mac, uint32_t phy_addr, uint32_t phy_reg, uint32_t *reg_value)¶ Read PHY register.
- Return
ESP_OK: read PHY register successfully
ESP_ERR_INVALID_ARG: read PHY register failed because of invalid argument
ESP_ERR_INVALID_STATE: read PHY register failed because of wrong state of MAC
ESP_ERR_TIMEOUT: read PHY register failed because of timeout
ESP_FAIL: read PHY register failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] phy_addr
: PHY chip address (0~31)[in] phy_reg
: PHY register index code[out] reg_value
: PHY register value
-
esp_err_t (*
write_phy_reg
)(esp_eth_mac_t *mac, uint32_t phy_addr, uint32_t phy_reg, uint32_t reg_value)¶ Write PHY register.
- Return
ESP_OK: write PHY register successfully
ESP_ERR_INVALID_STATE: write PHY register failed because of wrong state of MAC
ESP_ERR_TIMEOUT: write PHY register failed because of timeout
ESP_FAIL: write PHY register failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] phy_addr
: PHY chip address (0~31)[in] phy_reg
: PHY register index code[in] reg_value
: PHY register value
-
esp_err_t (*
set_addr
)(esp_eth_mac_t *mac, uint8_t *addr)¶ Set MAC address.
- Return
ESP_OK: set MAC address successfully
ESP_ERR_INVALID_ARG: set MAC address failed because of invalid argument
ESP_FAIL: set MAC address failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] addr
: MAC address
-
esp_err_t (*
get_addr
)(esp_eth_mac_t *mac, uint8_t *addr)¶ Get MAC address.
- Return
ESP_OK: get MAC address successfully
ESP_ERR_INVALID_ARG: get MAC address failed because of invalid argument
ESP_FAIL: get MAC address failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[out] addr
: MAC address
-
esp_err_t (*
set_speed
)(esp_eth_mac_t *mac, eth_speed_t speed)¶ Set speed of MAC.
- Return
ESP_OK: set MAC speed successfully
ESP_ERR_INVALID_ARG: set MAC speed failed because of invalid argument
ESP_FAIL: set MAC speed failed because some other error occurred
- Parameters
[in] ma:c
: Ethernet MAC instance[in] speed
: MAC speed
-
esp_err_t (*
set_duplex
)(esp_eth_mac_t *mac, eth_duplex_t duplex)¶ Set duplex mode of MAC.
- Return
ESP_OK: set MAC duplex mode successfully
ESP_ERR_INVALID_ARG: set MAC duplex failed because of invalid argument
ESP_FAIL: set MAC duplex failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] duplex
: MAC duplex
-
esp_err_t (*
set_link
)(esp_eth_mac_t *mac, eth_link_t link)¶ Set link status of MAC.
- Return
ESP_OK: set link status successfully
ESP_ERR_INVALID_ARG: set link status failed because of invalid argument
ESP_FAIL: set link status failed because some other error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] link
: Link status
-
esp_err_t (*
set_promiscuous
)(esp_eth_mac_t *mac, bool enable)¶ Set promiscuous of MAC.
- Return
ESP_OK: set promiscuous mode successfully
ESP_FAIL: set promiscuous mode failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] enable
: set true to enable promiscuous mode; set false to disable promiscuous mode
-
esp_err_t (*
enable_flow_ctrl
)(esp_eth_mac_t *mac, bool enable)¶ Enable flow control on MAC layer or not.
- Return
ESP_OK: set flow control successfully
ESP_FAIL: set flow control failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] enable
: set true to enable flow control; set false to disable flow control
-
esp_err_t (*
set_peer_pause_ability
)(esp_eth_mac_t *mac, uint32_t ability)¶ Set the PAUSE ability of peer node.
- Return
ESP_OK: set peer pause ability successfully
ESP_FAIL: set peer pause ability failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance[in] ability
: zero indicates that pause function is supported by link partner; non-zero indicates that pause function is not supported by link partner
-
esp_err_t (*
del
)(esp_eth_mac_t *mac)¶ Free memory of Ethernet MAC.
- Return
ESP_OK: free Ethernet MAC instance successfully
ESP_FAIL: free Ethernet MAC instance failed because some error occurred
- Parameters
[in] mac
: Ethernet MAC instance
-
esp_err_t (*
-
struct
eth_mac_config_t
¶ Configuration of Ethernet MAC object.
Public Members
-
uint32_t
sw_reset_timeout_ms
¶ Software reset timeout value (Unit: ms)
-
uint32_t
rx_task_stack_size
¶ Stack size of the receive task
-
uint32_t
rx_task_prio
¶ Priority of the receive task
-
int
smi_mdc_gpio_num
¶ SMI MDC GPIO number, set to -1 could bypass the SMI GPIO configuration
-
int
smi_mdio_gpio_num
¶ SMI MDIO GPIO number, set to -1 could bypass the SMI GPIO configuration
-
uint32_t
flags
¶ Flags that specify extra capability for mac driver
-
uint32_t
Macros¶
-
ETH_MAC_FLAG_WORK_WITH_CACHE_DISABLE
¶ MAC driver can work when cache is disabled
-
ETH_MAC_FLAG_PIN_TO_CORE
¶ Pin MAC task to the CPU core where driver installation happened
-
ETH_MAC_DEFAULT_CONFIG
()¶ Default configuration for Ethernet MAC object.
Type Definitions¶
-
typedef struct esp_eth_mac_s
esp_eth_mac_t
¶ Ethernet MAC.
Header File¶
Functions¶
-
esp_eth_phy_t *
esp_eth_phy_new_ip101
(const eth_phy_config_t *config)¶ Create a PHY instance of IP101.
- Return
instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred
- Parameters
[in] config
: configuration of PHY
-
esp_eth_phy_t *
esp_eth_phy_new_rtl8201
(const eth_phy_config_t *config)¶ Create a PHY instance of RTL8201.
- Return
instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred
- Parameters
[in] config
: configuration of PHY
-
esp_eth_phy_t *
esp_eth_phy_new_lan8720
(const eth_phy_config_t *config)¶ Create a PHY instance of LAN8720.
- Return
instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred
- Parameters
[in] config
: configuration of PHY
-
esp_eth_phy_t *
esp_eth_phy_new_dp83848
(const eth_phy_config_t *config)¶ Create a PHY instance of DP83848.
- Return
instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred
- Parameters
[in] config
: configuration of PHY
-
esp_eth_phy_t *
esp_eth_phy_new_ksz8041
(const eth_phy_config_t *config)¶ Create a PHY instance of KSZ8041.
- Return
instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred
- Parameters
[in] config
: configuration of PHY
Structures¶
-
struct
esp_eth_phy_s
¶ Ethernet PHY.
Public Members
-
esp_err_t (*
set_mediator
)(esp_eth_phy_t *phy, esp_eth_mediator_t *mediator)¶ Set mediator for PHY.
- Return
ESP_OK: set mediator for Ethernet PHY instance successfully
ESP_ERR_INVALID_ARG: set mediator for Ethernet PHY instance failed because of some invalid arguments
- Parameters
[in] phy
: Ethernet PHY instance[in] mediator
: mediator of Ethernet driver
-
esp_err_t (*
reset
)(esp_eth_phy_t *phy)¶ Software Reset Ethernet PHY.
- Return
ESP_OK: reset Ethernet PHY successfully
ESP_FAIL: reset Ethernet PHY failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
reset_hw
)(esp_eth_phy_t *phy)¶ Hardware Reset Ethernet PHY.
- Note
Hardware reset is mostly done by pull down and up PHY’s nRST pin
- Return
ESP_OK: reset Ethernet PHY successfully
ESP_FAIL: reset Ethernet PHY failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
init
)(esp_eth_phy_t *phy)¶ Initialize Ethernet PHY.
- Return
ESP_OK: initialize Ethernet PHY successfully
ESP_FAIL: initialize Ethernet PHY failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
deinit
)(esp_eth_phy_t *phy)¶ Deinitialize Ethernet PHY.
- Return
ESP_OK: deinitialize Ethernet PHY successfully
ESP_FAIL: deinitialize Ethernet PHY failed because some error occurred
- Parameters
[in] phyL
: Ethernet PHY instance
-
esp_err_t (*
negotiate
)(esp_eth_phy_t *phy)¶ Start auto negotiation.
- Return
ESP_OK: restart auto negotiation successfully
ESP_FAIL: restart auto negotiation failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
get_link
)(esp_eth_phy_t *phy)¶ Get Ethernet PHY link status.
- Return
ESP_OK: get Ethernet PHY link status successfully
ESP_FAIL: get Ethernet PHY link status failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
pwrctl
)(esp_eth_phy_t *phy, bool enable)¶ Power control of Ethernet PHY.
- Return
ESP_OK: control Ethernet PHY power successfully
ESP_FAIL: control Ethernet PHY power failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance[in] enable
: set true to power on Ethernet PHY; ser false to power off Ethernet PHY
-
esp_err_t (*
set_addr
)(esp_eth_phy_t *phy, uint32_t addr)¶ Set PHY chip address.
- Return
ESP_OK: set Ethernet PHY address successfully
ESP_FAIL: set Ethernet PHY address failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance[in] addr
: PHY chip address
-
esp_err_t (*
get_addr
)(esp_eth_phy_t *phy, uint32_t *addr)¶ Get PHY chip address.
- Return
ESP_OK: get Ethernet PHY address successfully
ESP_ERR_INVALID_ARG: get Ethernet PHY address failed because of invalid argument
- Parameters
[in] phy
: Ethernet PHY instance[out] addr
: PHY chip address
-
esp_err_t (*
advertise_pause_ability
)(esp_eth_phy_t *phy, uint32_t ability)¶ Advertise pause function supported by MAC layer.
- Return
ESP_OK: Advertise pause ability successfully
ESP_ERR_INVALID_ARG: Advertise pause ability failed because of invalid argument
- Parameters
[in] phy
: Ethernet PHY instance[out] addr
: Pause ability
-
esp_err_t (*
del
)(esp_eth_phy_t *phy)¶ Free memory of Ethernet PHY instance.
- Return
ESP_OK: free PHY instance successfully
ESP_FAIL: free PHY instance failed because some error occurred
- Parameters
[in] phy
: Ethernet PHY instance
-
esp_err_t (*
-
struct
eth_phy_config_t
¶ Ethernet PHY configuration.
Public Members
-
int32_t
phy_addr
¶ PHY address, set -1 to enable PHY address detection at initialization stage
-
uint32_t
reset_timeout_ms
¶ Reset timeout value (Unit: ms)
-
uint32_t
autonego_timeout_ms
¶ Auto-negotiation timeout value (Unit: ms)
-
int
reset_gpio_num
¶ Reset GPIO number, -1 means no hardware reset
-
int32_t
Macros¶
-
ESP_ETH_PHY_ADDR_AUTO
¶
-
ETH_PHY_DEFAULT_CONFIG
()¶ Default configuration for Ethernet PHY object.
Type Definitions¶
-
typedef struct esp_eth_phy_s
esp_eth_phy_t
¶ Ethernet PHY.
Header File¶
Functions¶
-
void *
esp_eth_new_netif_glue
(esp_eth_handle_t eth_hdl)¶ Create a netif glue for Ethernet driver.
- Note
netif glue is used to attach io driver to TCP/IP netif
- Return
glue object, which inherits esp_netif_driver_base_t
- Parameters
eth_hdl
: Ethernet driver handle
-
esp_err_t
esp_eth_del_netif_glue
(void *glue)¶ Delete netif glue of Ethernet driver.
- Return
-ESP_OK: delete netif glue successfully
- Parameters
glue
: netif glue
-
esp_err_t
esp_eth_set_default_handlers
(void *esp_netif)¶ Register default IP layer handlers for Ethernet.
- Note
: Ethernet handle might not yet properly initialized when setting up these default handlers
- Return
ESP_ERR_INVALID_ARG: invalid parameter (esp_netif is NULL)
ESP_OK: set default IP layer handlers successfully
others: other failure occurred during register esp_event handler
- Parameters
[in] esp_netif
: esp network interface handle created for Ethernet driver
-
esp_err_t
esp_eth_clear_default_handlers
(void *esp_netif)¶ Unregister default IP layer handlers for Ethernet.
- Return
ESP_ERR_INVALID_ARG: invalid parameter (esp_netif is NULL)
ESP_OK: clear default IP layer handlers successfully
others: other failure occurred during unregister esp_event handler
- Parameters
[in] esp_netif
: esp network interface handle created for Ethernet driver