以太网

[英文]

应用示例

以太网驱动程序模型

以太网通用接口

以太网 MAC 接口

以太网 PHY 接口

以太网 PHY 公共寄存器

API 参考 – 驱动程序模型

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 to stack_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.

The following IO control commands are supported:

  • ETH_CMD_S_MAC_ADDR sets Ethernet interface MAC address. data argument is pointer to MAC address buffer with expected size of 6 bytes.

  • ETH_CMD_G_MAC_ADDR gets Ethernet interface MAC address. data argument is pointer to a buffer to which MAC address is to be copied. The buffer size must be at least 6 bytes.

  • ETH_CMD_S_PHY_ADDR sets PHY address in range of <0-31>. data argument is pointer to memory of uint32_t datatype from where the configuration option is read.

  • ETH_CMD_G_PHY_ADDR gets PHY address. data argument is pointer to memory of uint32_t datatype to which the PHY address is to be stored.

  • ETH_CMD_G_SPEED gets current Ethernet link speed. data argument is pointer to memory of eth_speed_t datatype to which the speed is to be stored.

  • ETH_CMD_S_PROMISCUOUS sets/resets Ethernet interface promiscuous mode. data argument is pointer to memory of bool datatype from which the configuration option is read.

  • ETH_CMD_S_FLOW_CTRL sets/resets Ethernet interface flow control. data argument is pointer to memory of bool datatype from which the configuration option is read.

  • ETH_CMD_G_DUPLEX_MODE gets current Ethernet link duplex mode. data argument is pointer to memory of eth_duplex_t datatype to which the duplex mode is to be stored.

  • ETH_CMD_S_PHY_LOOPBACK sets/resets PHY to/from loopback mode. data argument is pointer to memory of bool datatype from which the configuration option is read.

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

  • [inout] data: address of data for set command or address where to store the data when used with get 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_err_t (*read_phy_reg)(esp_eth_handle_t eth_handle, uint32_t phy_addr, uint32_t phy_reg, uint32_t *reg_value)

Read PHY register.

Note

Usually the PHY register read/write function is provided by MAC (SMI interface), but if the PHY device is managed by other interface (e.g. I2C), then user needs to implement the corresponding read/write. Setting this to NULL means your PHY device is managed by MAC’s SMI interface.

Return

  • ESP_OK: read PHY register successfully

  • ESP_ERR_INVALID_ARG: read PHY register failed because of invalid argument

  • ESP_ERR_TIMEOUT: read PHY register failed because of timeout

  • ESP_FAIL: read PHY register failed because some other error occurred

Parameters

  • [in] eth_handle: handle 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 (*write_phy_reg)(esp_eth_handle_t eth_handle, uint32_t phy_addr, uint32_t phy_reg, uint32_t reg_value)

Write PHY register.

Note

Usually the PHY register read/write function is provided by MAC (SMI interface), but if the PHY device is managed by other interface (e.g. I2C), then user needs to implement the corresponding read/write. Setting this to NULL means your PHY device is managed by MAC’s SMI interface.

Return

  • ESP_OK: write PHY register successfully

  • ESP_ERR_INVALID_ARG: read PHY register failed because of invalid argument

  • ESP_ERR_TIMEOUT: write PHY register failed because of timeout

  • ESP_FAIL: write PHY register failed because some other error occurred

Parameters

  • [in] eth_handle: handle of Ethernet driver

  • [in] phy_addr: PHY chip address (0~31)

  • [in] phy_reg: PHY register index code

  • [in] reg_value: PHY register value

Macros

ETH_DEFAULT_CONFIG(emac, ephy)

Default configuration for Ethernet driver.

Type Definitions

typedef void *esp_eth_handle_t

Handle of Ethernet driver.

API 参考 – 通用接口

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

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_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

ETH_CMD_S_PHY_LOOPBACK

Set PHY loopback

enum eth_event_t

Ethernet event declarations.

Values:

ETHERNET_EVENT_START

Ethernet driver start

ETHERNET_EVENT_STOP

Ethernet driver stop

ETHERNET_EVENT_CONNECTED

Ethernet got a valid link

ETHERNET_EVENT_DISCONNECTED

Ethernet lost a valid link

API 参考 – MAC 接口

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

Unions

union eth_mac_clock_config_t
#include <esp_eth_mac.h>

Ethernet MAC Clock Configuration.

Public Members

struct eth_mac_clock_config_t::[anonymous] mii

EMAC MII Clock Configuration

emac_rmii_clock_mode_t clock_mode

RMII Clock Mode Configuration

emac_rmii_clock_gpio_t clock_gpio

RMII Clock GPIO Configuration

struct eth_mac_clock_config_t::[anonymous] rmii

EMAC RMII Clock 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

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

eth_data_interface_t interface

EMAC Data interface to PHY (MII/RMII)

eth_mac_clock_config_t clock_config

EMAC Interface clock configuration

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.

Enumerations

enum emac_rmii_clock_mode_t

RMII Clock Mode Options.

Values:

EMAC_CLK_DEFAULT

Default values configured using Kconfig are going to be used when “Default” selected.

EMAC_CLK_EXT_IN

Input RMII Clock from external. EMAC Clock GPIO number needs to be configured when this option is selected.

Note

MAC will get RMII clock from outside. Note that ESP32 only supports GPIO0 to input the RMII clock.

EMAC_CLK_OUT

Output RMII Clock from internal APLL Clock. EMAC Clock GPIO number needs to be configured when this option is selected.

enum emac_rmii_clock_gpio_t

RMII Clock GPIO number Options.

Values:

EMAC_CLK_IN_GPIO = 0

MAC will get RMII clock from outside at this GPIO.

Note

ESP32 only supports GPIO0 to input the RMII clock.

EMAC_APPL_CLK_OUT_GPIO = 0

Output RMII Clock from internal APLL Clock available at GPIO0.

Note

GPIO0 can be set to output a pre-divided PLL clock (test only!). Enabling this option will configure GPIO0 to output a 50MHz clock. In fact this clock doesn’t have directly relationship with EMAC peripheral. Sometimes this clock won’t work well with your PHY chip. You might need to add some extra devices after GPIO0 (e.g. inverter). Note that outputting RMII clock on GPIO0 is an experimental practice. If you want the Ethernet to work with WiFi, don’t select GPIO0 output mode for stability.

EMAC_CLK_OUT_GPIO = 16

Output RMII Clock from internal APLL Clock available at GPIO16.

EMAC_CLK_OUT_180_GPIO = 17

Inverted Output RMII Clock from internal APLL Clock available at GPIO17.

API 参考 – PHY 接口

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_lan87xx(const eth_phy_config_t *config)

Create a PHY instance of LAN87xx.

Return

  • instance: create PHY instance successfully

  • NULL: create PHY instance failed because some error occurred

Parameters

  • [in] config: configuration of PHY

static esp_eth_phy_t *esp_eth_phy_new_lan8720(const eth_phy_config_t *config)

Create a PHY instance of LAN8720.

Note

For ESP-IDF backwards compatibility reasons. In all other cases, use esp_eth_phy_new_lan87xx instead.

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

esp_eth_phy_t *esp_eth_phy_new_ksz8081(const eth_phy_config_t *config)

Create a PHY instance of KSZ8081.

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 (*loopback)(esp_eth_phy_t *phy, bool enable)

Return

  • ESP_OK: configures PHY instance loopback function successfully

  • ESP_FAIL: PHY instance loopback configuration failed because some error occurred

Parameters

  • [in] phy: Ethernet PHY instance

  • [in] enable: enables or disables PHY loopback

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

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

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.

API 参考 – esp_netif 相关使用

Functions

esp_eth_netif_glue_handle_t 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(esp_eth_netif_glue_handle_t eth_netif_glue)

Delete netif glue of Ethernet driver.

Return

-ESP_OK: delete netif glue successfully

Parameters

  • eth_netif_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

Warning

: This function is deprecated and is kept here only for compatibility reasons. Registration of default IP layer handlers for Ethernet is now handled automatically. Do not call this function if you want to use multiple Ethernet instances at a time.

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.

Warning

: This function is deprecated and is kept here only for compatibility reasons. Unregistration of default IP layer handlers for Ethernet is now handled automatically if not registered by calling esp_eth_set_default_handlers.

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

Type Definitions

typedef struct esp_eth_netif_glue_t *esp_eth_netif_glue_handle_t

Handle of netif glue - an intermediate layer between netif and Ethernet driver.

提供有关此文档的反馈