Ethernet

Application Example

Ethernet Driver Model

Ethernet Common Interface

Ethernet MAC Interface

Ethernet PHY Interface

Ethernet PHY Common Registers

API Reference - Driver Model

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
  • config: configuration of the Ethernet driver
  • 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
  • hdl: handle of Ethernet driver

esp_err_t esp_eth_start(esp_eth_handle_t hdl)

Start Ethernet driver.

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
  • 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
  • hdl: handle of Ethernet driver

esp_err_t esp_eth_transmit(esp_eth_handle_t hdl, uint8_t *buf, uint32_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
  • hdl: handle of Ethernet driver
  • buf: buffer of the packet to transfer
  • 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.

Return
  • ESP_OK: receive frame buffer successfully
  • ESP_ERR_INVALID_ARG: receive frame buffer failed because of some invalid argument
  • ESP_FAIL: receive frame buffer failed because some other error occurred
Parameters
  • hdl: handle of Ethernet driver
  • buf: buffer to preserve the received packet
  • 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
  • hdl: handle of Ethernet driver
  • cmd: IO control command
  • 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
  • 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
  • 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)

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
  • eth_handle: handle of Ethernet driver
  • buffer: frame buffer that will get input to upper stack
  • 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
  • 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
  • eth_handle: handle of Ethernet driver

Macros

ETH_DEFAULT_CONFIG(emac, ephy)

Default configuration for Ethernet driver.

Type Definitions

typedef void *esp_eth_handle_t

Handle of Ethernet driver.

API Reference - Common Interface

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
  • eth: mediator of Ethernet driver
  • phy_addr: PHY Chip address (0~31)
  • phy_reg: PHY register index code
  • 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
  • eth: mediator of Ethernet driver
  • phy_addr: PHY Chip address (0~31)
  • phy_reg: PHY register index code
  • 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
  • eth: mediator of Ethernet driver
  • buffer: packet buffer
  • 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
  • eth: mediator of Ethernet driver
  • state: new state
  • 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_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

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

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

enum eth_duplex_t

Ethernet duplex mode.

Values:

ETH_DUPLEX_HALF

Ethernet is in half duplex

ETH_DUPLEX_FULL

Ethernet is in full duplex

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 Reference - MAC Interface

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
  • mac: Ethernet MAC instance
  • 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
  • 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
  • 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
  • mac: Ethernet MAC instance
  • buf: packet buffer to transmit
  • 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.
Return
  • ESP_OK: receive packet successfully
  • ESP_ERR_INVALID_ARG: receive packet failed because of invalid argument
  • ESP_FAIL: receive packet failed because some other error occurred
Parameters
  • mac: Ethernet MAC instance
  • buf: packet buffer which will preserve the received frame
  • 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
  • mac: Ethernet MAC instance
  • phy_addr: PHY chip address (0~31)
  • phy_reg: PHY register index code
  • 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
  • mac: Ethernet MAC instance
  • phy_addr: PHY chip address (0~31)
  • phy_reg: PHY register index code
  • 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
  • mac: Ethernet MAC instance
  • 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
  • mac: Ethernet MAC instance
  • 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
  • ma:c: Ethernet MAC instance
  • 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
  • mac: Ethernet MAC instance
  • 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
  • mac: Ethernet MAC instance
  • 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
  • mac: Ethernet MAC instance
  • enable: set true to enable promiscuous mode; set false to disable promiscuous mode

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

int smi_mdio_gpio_num

SMI MDIO GPIO number

Macros

ETH_MAC_DEFAULT_CONFIG()

Default configuration for Ethernet MAC object.

Type Definitions

typedef struct esp_eth_mac_s esp_eth_mac_t

Ethernet MAC.

API Reference - PHY Interface

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
  • 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
  • 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
  • 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
  • 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
  • phy: Ethernet PHY instance
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • 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
  • phy: Ethernet PHY instance
  • 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
  • phy: Ethernet PHY instance
  • 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
  • phy: Ethernet PHY instance
  • addr: PHY chip address

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
  • phy: Ethernet PHY instance

struct eth_phy_config_t

Ethernet PHY configuration.

Public Members

uint32_t phy_addr

PHY address

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

ETH_PHY_DEFAULT_CONFIG()

Default configuration for Ethernet PHY object.

Type Definitions

typedef struct esp_eth_phy_s esp_eth_phy_t

Ethernet PHY.