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.

Return
  • ESP_OK: uninstall esp_eth driver successfully
  • ESP_ERR_INVALID_ARG: uninstall esp_eth driver failed because of some invalid argument
  • ESP_FAIL: uninstall 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

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.

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

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

Ethernet link status.

Values:

Ethernet link is up

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

uint32_t queue_len

Length of the transaction queue

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)

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 (*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)

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.