以太网

[英文]

应用示例

以太网基本示例：ethernet/basic.
以太网 iperf 示例：ethernet/iperf.

以太网驱动程序模型

esp_eth/include/esp_eth.h

以太网通用接口

esp_eth/include/esp_eth_com.h

以太网 MAC 接口

esp_eth/include/esp_eth_mac.h

以太网 PHY 接口

esp_eth/include/esp_eth_phy.h

以太网 PHY 公共寄存器

esp_eth/include/eth_phy_regs_struct.h

API 参考 – 驱动程序模型

Header File

components/esp_eth/include/esp_eth.h

Functions

esp_err_t esp_eth_driver_install(const esp_eth_config_t *config, esp_eth_handle_t *out_hdl)

Install Ethernet driver.

参数

config – [in] configuration of the Ethernet driver
out_hdl – [out] handle of Ethernet driver

返回

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

esp_err_t esp_eth_driver_uninstall(esp_eth_handle_t hdl)

Uninstall Ethernet driver.

备注

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.

参数

hdl – [in] handle of Ethernet driver

返回

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

esp_err_t esp_eth_start(esp_eth_handle_t hdl)

Start Ethernet driver ONLY in standalone mode (i.e. without TCP/IP stack)

备注

This API will start driver state machine and internal software timer (for checking link status).

参数

hdl – [in] handle of Ethernet driver

返回

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

esp_err_t esp_eth_stop(esp_eth_handle_t hdl)

Stop Ethernet driver.

备注

This function does the oppsite operation of esp_eth_start.

参数

hdl – [in] handle of Ethernet driver

返回

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

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)

备注

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.

参数

hdl – [in] handle of Ethernet driver
stack_input – [in] function pointer, which does the actual process on incoming packets
priv – [in] private resource, which gets passed to stack_input callback without any modification

返回

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

esp_err_t esp_eth_transmit(esp_eth_handle_t hdl, void *buf, size_t length)

General Transmit.

参数

hdl – [in] handle of Ethernet driver
buf – [in] buffer of the packet to transfer
length – [in] length of the buffer to transfer

返回

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

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.

备注

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.

备注

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.

参数

hdl – [in] handle of Ethernet driver
buf – [out] buffer to preserve the received packet
length – [out] length of the received packet

返回

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

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.

参数

hdl – [in] handle of Ethernet driver
cmd – [in] IO control command
data – [inout] address of data for set command or address where to store the data when used with get command

返回

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

esp_err_t esp_eth_increase_reference(esp_eth_handle_t hdl)

Increase Ethernet driver reference.

备注

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.

参数

hdl – [in] handle of Ethernet driver

返回

ESP_OK: increase reference successfully
ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument

esp_err_t esp_eth_decrease_reference(esp_eth_handle_t hdl)

Decrease Ethernet driver reference.

参数

hdl – [in] handle of Ethernet driver

返回

ESP_OK: increase reference successfully
ESP_ERR_INVALID_ARG: increase reference failed because of some invalid argument

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.

Param eth_handle

[in] handle of Ethernet driver

Param buffer

[in] frame buffer that will get input to upper stack

Param length

[in] length of the frame buffer

Return

ESP_OK: input frame buffer to upper stack successfully
ESP_FAIL: error occurred when inputting buffer to upper stack

esp_err_t (*on_lowlevel_init_done)(esp_eth_handle_t eth_handle)

Callback function invoked when lowlevel initialization is finished.

Param eth_handle

[in] handle of Ethernet driver

Return

ESP_OK: process extra lowlevel initialization successfully
ESP_FAIL: error occurred when processing extra lowlevel initialization

esp_err_t (*on_lowlevel_deinit_done)(esp_eth_handle_t eth_handle)

Callback function invoked when lowlevel deinitialization is finished.

Param eth_handle

[in] handle of Ethernet driver

Return

ESP_OK: process extra lowlevel deinitialization successfully
ESP_FAIL: error occurred when processing extra lowlevel deinitialization

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.

备注

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.

Param eth_handle

[in] handle of Ethernet driver

Param phy_addr

[in] PHY chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[out] PHY register value

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

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.

备注

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.

Param eth_handle

[in] handle of Ethernet driver

Param phy_addr

[in] PHY chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[in] PHY register value

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

Macros

ETH_DEFAULT_CONFIG(emac, ephy): Default configuration for Ethernet driver.

Type Definitions

typedef void *esp_eth_handle_t: Handle of Ethernet driver.

API 参考 – 通用接口

Header File

components/esp_eth/include/esp_eth_com.h

Functions

esp_err_t esp_eth_detect_phy_addr(esp_eth_mediator_t *eth, int *detected_addr)

Detect PHY address.

参数

eth – [in] mediator of Ethernet driver
detected_addr – [out] a valid address after detection

返回

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

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.

Param eth

[in] mediator of Ethernet driver

Param phy_addr

[in] PHY Chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[out] PHY register value

Return

ESP_OK: read PHY register successfully
ESP_FAIL: read PHY register failed because some error occurred

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.

Param eth

[in] mediator of Ethernet driver

Param phy_addr

[in] PHY Chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[in] PHY register value

Return

ESP_OK: write PHY register successfully
ESP_FAIL: write PHY register failed because some error occurred

esp_err_t (*stack_input)(esp_eth_mediator_t *eth, uint8_t *buffer, uint32_t length)

Deliver packet to upper stack.

Param eth

[in] mediator of Ethernet driver

Param buffer

[in] packet buffer

Param length

[in] length of the packet

Return

ESP_OK: deliver packet to upper stack successfully
ESP_FAIL: deliver packet failed because some error occurred

esp_err_t (*on_state_changed)(esp_eth_mediator_t *eth, esp_eth_state_t state, void *args)

Callback on Ethernet state changed.

Param eth

[in] mediator of Ethernet driver

Param state

[in] new state

Param args

[in] optional argument for the new state

Return

ESP_OK: process the new state successfully
ESP_FAIL: process the new state failed because some error occurred

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:

enumerator ETH_STATE_LLINIT: Lowlevel init done

enumerator ETH_STATE_DEINIT: Deinit done

enumerator ETH_STATE_LINK: Link status changed

enumerator ETH_STATE_SPEED: Speed updated

enumerator ETH_STATE_DUPLEX: Duplex updated

enumerator ETH_STATE_PAUSE: Pause ability updated

enum esp_eth_io_cmd_t

Command list for ioctl API.

Values:

enumerator ETH_CMD_G_MAC_ADDR: Get MAC address

enumerator ETH_CMD_S_MAC_ADDR: Set MAC address

enumerator ETH_CMD_G_PHY_ADDR: Get PHY address

enumerator ETH_CMD_S_PHY_ADDR: Set PHY address

enumerator ETH_CMD_G_SPEED: Get Speed

enumerator ETH_CMD_S_PROMISCUOUS: Set promiscuous mode

enumerator ETH_CMD_S_FLOW_CTRL: Set flow control

enumerator ETH_CMD_G_DUPLEX_MODE: Get Duplex mode

enumerator ETH_CMD_S_PHY_LOOPBACK: Set PHY loopback

enum eth_event_t

Ethernet event declarations.

Values:

enumerator ETHERNET_EVENT_START: Ethernet driver start

enumerator ETHERNET_EVENT_STOP: Ethernet driver stop

enumerator ETHERNET_EVENT_CONNECTED: Ethernet got a valid link

enumerator ETHERNET_EVENT_DISCONNECTED: Ethernet lost a valid link

API 参考 – MAC 接口

Header File

components/esp_eth/include/esp_eth_mac.h

Functions

esp_eth_mac_t *esp_eth_mac_new_esp32(const eth_mac_config_t *config)

Create ESP32 Ethernet MAC instance.

参数

config – Ethernet MAC configuration

返回

instance: create MAC instance successfully
NULL: create MAC instance failed because some error occurred

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.

Param mac

[in] Ethernet MAC instance

Param eth

[in] Ethernet mediator

Return

ESP_OK: set mediator for Ethernet MAC successfully
ESP_ERR_INVALID_ARG: set mediator for Ethernet MAC failed because of invalid argument

esp_err_t (*init)(esp_eth_mac_t *mac)

Initialize Ethernet MAC.

Param mac

[in] Ethernet MAC instance

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

esp_err_t (*deinit)(esp_eth_mac_t *mac)

Deinitialize Ethernet MAC.

Param mac

[in] Ethernet MAC instance

Return

ESP_OK: deinitialize Ethernet MAC successfully
ESP_FAIL: deinitialize Ethernet MAC failed because some error occurred

esp_err_t (*start)(esp_eth_mac_t *mac)

Start Ethernet MAC.

Param mac

[in] Ethernet MAC instance

Return

ESP_OK: start Ethernet MAC successfully
ESP_FAIL: start Ethernet MAC failed because some other error occurred

esp_err_t (*stop)(esp_eth_mac_t *mac)

Stop Ethernet MAC.

Param mac

[in] Ethernet MAC instance

Return

ESP_OK: stop Ethernet MAC successfully
ESP_FAIL: stop Ethernet MAC failed because some error occurred

esp_err_t (*transmit)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t length)

Transmit packet from Ethernet MAC.

Param mac

[in] Ethernet MAC instance

Param buf

[in] packet buffer to transmit

Param length

[in] length of packet

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

esp_err_t (*receive)(esp_eth_mac_t *mac, uint8_t *buf, uint32_t *length)

Receive packet from Ethernet MAC.

备注

Memory of buf is allocated in the Layer2, make sure it get free after process.

备注

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.

Param mac

[in] Ethernet MAC instance

Param buf

[out] packet buffer which will preserve the received frame

Param length

[out] length of the received packet

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

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.

Param mac

[in] Ethernet MAC instance

Param phy_addr

[in] PHY chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[out] PHY register value

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

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.

Param mac

[in] Ethernet MAC instance

Param phy_addr

[in] PHY chip address (0~31)

Param phy_reg

[in] PHY register index code

Param reg_value

[in] PHY register value

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

esp_err_t (*set_addr)(esp_eth_mac_t *mac, uint8_t *addr)

Set MAC address.

Param mac

[in] Ethernet MAC instance

Param addr

[in] 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

esp_err_t (*get_addr)(esp_eth_mac_t *mac, uint8_t *addr)

Get MAC address.

Param mac

[in] Ethernet MAC instance

Param addr

[out] 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

esp_err_t (*set_speed)(esp_eth_mac_t *mac, eth_speed_t speed)

Set speed of MAC.

Param ma:c

[in] Ethernet MAC instance

Param speed

[in] MAC speed

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

esp_err_t (*set_duplex)(esp_eth_mac_t *mac, eth_duplex_t duplex)

Set duplex mode of MAC.

Param mac

[in] Ethernet MAC instance

Param duplex

[in] MAC duplex

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

esp_err_t (*set_link)(esp_eth_mac_t *mac, eth_link_t link)

Set link status of MAC.

Param mac

[in] Ethernet MAC instance

Param link

[in] Link status

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

esp_err_t (*set_promiscuous)(esp_eth_mac_t *mac, bool enable)

Set promiscuous of MAC.

Param mac

[in] Ethernet MAC instance

Param enable

[in] set true to enable promiscuous mode; set false to disable promiscuous mode

Return

ESP_OK: set promiscuous mode successfully
ESP_FAIL: set promiscuous mode failed because some error occurred

esp_err_t (*enable_flow_ctrl)(esp_eth_mac_t *mac, bool enable)

Enable flow control on MAC layer or not.

Param mac

[in] Ethernet MAC instance

Param enable

[in] set true to enable flow control; set false to disable flow control

Return

ESP_OK: set flow control successfully
ESP_FAIL: set flow control failed because some error occurred

esp_err_t (*set_peer_pause_ability)(esp_eth_mac_t *mac, uint32_t ability)

Set the PAUSE ability of peer node.

Param mac

[in] Ethernet MAC instance

Param ability

[in] zero indicates that pause function is supported by link partner; non-zero indicates that pause function is not supported by link partner

Return

ESP_OK: set peer pause ability successfully
ESP_FAIL: set peer pause ability failed because some error occurred

esp_err_t (*del)(esp_eth_mac_t *mac)

Free memory of Ethernet MAC.

Param mac

[in] Ethernet MAC instance

Return

ESP_OK: free Ethernet MAC instance successfully
ESP_FAIL: free Ethernet MAC instance failed because some error occurred

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:

enumerator EMAC_CLK_DEFAULT: Default values configured using Kconfig are going to be used when “Default” selected.

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

备注

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

enumerator 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:

enumerator EMAC_CLK_IN_GPIO: MAC will get RMII clock from outside at this GPIO.

备注

ESP32 only supports GPIO0 to input the RMII clock.

enumerator EMAC_APPL_CLK_OUT_GPIO: Output RMII Clock from internal APLL Clock available at GPIO0.

备注

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.

enumerator EMAC_CLK_OUT_GPIO: Output RMII Clock from internal APLL Clock available at GPIO16.

enumerator EMAC_CLK_OUT_180_GPIO: Inverted Output RMII Clock from internal APLL Clock available at GPIO17.

API 参考 – PHY 接口

Header File

components/esp_eth/include/esp_eth_phy.h

Functions

esp_eth_phy_t *esp_eth_phy_new_ip101(const eth_phy_config_t *config)

Create a PHY instance of IP101.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

esp_eth_phy_t *esp_eth_phy_new_rtl8201(const eth_phy_config_t *config)

Create a PHY instance of RTL8201.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

esp_eth_phy_t *esp_eth_phy_new_lan87xx(const eth_phy_config_t *config)

Create a PHY instance of LAN87xx.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

static inline esp_eth_phy_t *esp_eth_phy_new_lan8720(const eth_phy_config_t *config)

Create a PHY instance of LAN8720.

备注

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

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

esp_eth_phy_t *esp_eth_phy_new_dp83848(const eth_phy_config_t *config)

Create a PHY instance of DP83848.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

esp_eth_phy_t *esp_eth_phy_new_ksz8041(const eth_phy_config_t *config)

Create a PHY instance of KSZ8041.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

esp_eth_phy_t *esp_eth_phy_new_ksz8081(const eth_phy_config_t *config)

Create a PHY instance of KSZ8081.

参数

config – [in] configuration of PHY

返回

instance: create PHY instance successfully
NULL: create PHY instance failed because some error occurred

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.

Param phy

[in] Ethernet PHY instance

Param mediator

[in] mediator of Ethernet driver

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

esp_err_t (*reset)(esp_eth_phy_t *phy)

Software Reset Ethernet PHY.

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: reset Ethernet PHY successfully
ESP_FAIL: reset Ethernet PHY failed because some error occurred

esp_err_t (*reset_hw)(esp_eth_phy_t *phy)

Hardware Reset Ethernet PHY.

备注

Hardware reset is mostly done by pull down and up PHY’s nRST pin

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: reset Ethernet PHY successfully
ESP_FAIL: reset Ethernet PHY failed because some error occurred

esp_err_t (*init)(esp_eth_phy_t *phy)

Initialize Ethernet PHY.

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: initialize Ethernet PHY successfully
ESP_FAIL: initialize Ethernet PHY failed because some error occurred

esp_err_t (*deinit)(esp_eth_phy_t *phy)

Deinitialize Ethernet PHY.

Param phyL

[in] Ethernet PHY instance

Return

ESP_OK: deinitialize Ethernet PHY successfully
ESP_FAIL: deinitialize Ethernet PHY failed because some error occurred

esp_err_t (*negotiate)(esp_eth_phy_t *phy)

Start auto negotiation.

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: restart auto negotiation successfully
ESP_FAIL: restart auto negotiation failed because some error occurred

esp_err_t (*get_link)(esp_eth_phy_t *phy)

Get Ethernet PHY link status.

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: get Ethernet PHY link status successfully
ESP_FAIL: get Ethernet PHY link status failed because some error occurred

esp_err_t (*pwrctl)(esp_eth_phy_t *phy, bool enable)

Power control of Ethernet PHY.

Param phy

[in] Ethernet PHY instance

Param enable

[in] set true to power on Ethernet PHY; ser false to power off Ethernet PHY

Return

ESP_OK: control Ethernet PHY power successfully
ESP_FAIL: control Ethernet PHY power failed because some error occurred

esp_err_t (*set_addr)(esp_eth_phy_t *phy, uint32_t addr)

Set PHY chip address.

Param phy

[in] Ethernet PHY instance

Param addr

[in] PHY chip address

Return

ESP_OK: set Ethernet PHY address successfully
ESP_FAIL: set Ethernet PHY address failed because some error occurred

esp_err_t (*get_addr)(esp_eth_phy_t *phy, uint32_t *addr)

Get PHY chip address.

Param phy

[in] Ethernet PHY instance

Param addr

[out] PHY chip address

Return

ESP_OK: get Ethernet PHY address successfully
ESP_ERR_INVALID_ARG: get Ethernet PHY address failed because of invalid argument

esp_err_t (*advertise_pause_ability)(esp_eth_phy_t *phy, uint32_t ability)

Advertise pause function supported by MAC layer.

Param phy

[in] Ethernet PHY instance

Param addr

[out] Pause ability

Return

ESP_OK: Advertise pause ability successfully
ESP_ERR_INVALID_ARG: Advertise pause ability failed because of invalid argument

esp_err_t (*loopback)(esp_eth_phy_t *phy, bool enable)

Param phy

[in] Ethernet PHY instance

Param enable

[in] enables or disables PHY loopback

Return

ESP_OK: configures PHY instance loopback function successfully
ESP_FAIL: PHY instance loopback configuration failed because some error occurred

esp_err_t (*del)(esp_eth_phy_t *phy)

Free memory of Ethernet PHY instance.

Param phy

[in] Ethernet PHY instance

Return

ESP_OK: free PHY instance successfully
ESP_FAIL: free PHY instance failed because some error occurred

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 相关使用

Header File

components/esp_eth/include/esp_eth_netif_glue.h

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.

备注

netif glue is used to attach io driver to TCP/IP netif

参数: eth_hdl – Ethernet driver handle
返回: glue object, which inherits esp_netif_driver_base_t

esp_err_t esp_eth_del_netif_glue(esp_eth_netif_glue_handle_t eth_netif_glue)

Delete netif glue of Ethernet driver.

参数: eth_netif_glue – netif glue
返回: -ESP_OK: delete netif glue successfully

esp_err_t esp_eth_set_default_handlers(void *esp_netif)

Register default IP layer handlers for Ethernet.

备注

: Ethernet handle might not yet properly initialized when setting up these default handlers

警告

: 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.

参数

esp_netif – [in] esp network interface handle created for Ethernet driver

返回

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

esp_err_t esp_eth_clear_default_handlers(void *esp_netif)

Unregister default IP layer handlers for Ethernet.

警告

: 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.

参数

esp_netif – [in] esp network interface handle created for Ethernet driver

返回

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

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.

提供有关此文档的反馈