乙太網路¶

EMAC、lwIP 網路介面與乙太網路 PHY。說明取自標頭檔註解（英文）。

標頭	函式	說明
`hal_emac.h`	22	Ethernet MAC (EMAC) driver: initialization, buffer-descriptor TX/RX, MDIO access to the PHY and interrupt hooks.
`hal_ethernetif.h`	3	lwIP network interface for the Ethernet MAC: interface setup, link handling and DHCP client.
`ethernet_phy.h`	2	Ethernet PHY driver: configuration, auto-negotiation and link status.

hal_emac.h¶

#include "hal_emac.h"（原始碼）

Ethernet MAC (EMAC) driver: initialization, buffer-descriptor TX/RX, MDIO access to the PHY and interrupt hooks.

The EMAC moves frames through a table of hardware buffer descriptors (BDs): the TX descriptors come first, followed by the RX descriptors. Each descriptor points at one frame buffer. Typical sequence:

emac_init() - pins, clock, MAC configuration and interrupt handler.
emac_phy_init() (ethernet_phy.h) - PHY reset and auto-negotiation.
emac_bd_init() - descriptor rings and their buffers.
emac_start() - enable the transmitter and the receiver.
emac_bd_tx_enqueue() / emac_bd_rx_dequeue() - move frames.

Most applications do not call these functions directly but use the lwIP network interface in hal_ethernetif.h, which runs this sequence. The driver controls EMAC instance 0.

emac_init¶

int emac_init(emac_device_t *emac_cfg);

Initialize the EMAC: pins, clock, MAC settings and interrupt handler.

Configures GPIO3-GPIO7 and GPIO36-GPIO39 as EMAC pins, then drives GPIO40 as the PHY reset line (low for 10 ms, then high, followed by a 150 ms wait). Enables the EMAC clock, selects the external 50 MHz RMII reference clock and programs the MAC: the MAC address from emac_cfg, SPEED_SEL_MODE, hardware padding and CRC generation, 64-byte minimum and ETH_MAX_PACKET_SIZE maximum frame length, reception of broadcast frames and promiscuous mode (address filtering is left to the network stack). Finally registers the EMAC interrupt handler and unmasks all EMAC interrupts. The transmitter and receiver stay disabled until emac_start().

參數	說明
`emac_cfg`	MAC configuration; only `mac_addr` is used.

回傳值：0 (always).

注意

Blocking for about 160 ms because of the PHY reset sequence.

emac_bd_init¶

int emac_bd_init(uint8_t *eth_tx_buff, uint8_t tx_buf_count, uint8_t *eth_rx_buff, uint8_t rx_buf_count);

Set up the TX and RX buffer-descriptor rings.

Descriptor i of each ring points at offset i * ETH_MAX_PACKET_SIZE of its buffer area. TX descriptors start empty; RX descriptors are handed to the EMAC, ready to receive. Resets the driver's ring indexes.

參數	說明
`eth_tx_buff`	TX buffer area of `tx_buf_count * ETH_MAX_PACKET_SIZE` bytes, or NULL to leave the TX buffer addresses at 0 (then only `EMAC_NOCOPY_PACKET` transmissions work).
`tx_buf_count`	Number of TX descriptors (at least 1).
`eth_rx_buff`	RX buffer area of `rx_buf_count * ETH_MAX_PACKET_SIZE` bytes.
`rx_buf_count`	Number of RX descriptors (at least 1).

回傳值：0 (always).

前置條件：emac_init() has been called; the transmitter and receiver are stopped.

注意

The driver does no cache maintenance: place both buffer areas in non-cacheable memory (hal_ethernetif.c uses ATTR_NOCACHE_NOINIT_RAM_SECTION).

emac_bd_fragment_support¶

int emac_bd_fragment_support(void);

Tell whether emac_bd_tx_enqueue() accepts frames split over several descriptors.

回傳值：1 (fragmented frames are supported, see EMAC_FRAGMENT_PACKET).

emac_bd_tx_enqueue¶

int emac_bd_tx_enqueue(uint32_t flags, uint32_t len, const uint8_t *data_in);

Queue one frame, or one fragment of a frame, on the next TX descriptor.

Unless EMAC_NOCOPY_PACKET is given, the data is copied into the descriptor's buffer. The descriptor is then handed to the EMAC, which pads short frames and appends the CRC; it transmits once the transmitter is enabled (emac_start() or emac_start_tx()). Non-blocking.

參數	說明
`flags`	`EMAC_NORMAL_PACKET`, or a combination of `EMAC_FRAGMENT_PACKET` and `EMAC_NOCOPY_PACKET`.
`len`	Number of bytes in `data_in`, without the CRC. When copying, at most `ETH_MAX_PACKET_SIZE` (not checked).
`data_in`	Frame data, starting with the destination MAC address.

回傳碼	說明
`0`	Queued.
`NORESC`	The next TX descriptor is still owned by the EMAC (ring full); nothing was queued.

前置條件：emac_bd_init() has been called.

注意

No locking: call from one context only, and not together with the lwIP interface of hal_ethernetif.h, which drives the same descriptors.

警告

With EMAC_NOCOPY_PACKET the descriptor keeps pointing at data_in afterwards: keep that memory valid until the frame is sent, and note that later copy-mode frames on the same descriptor are written into it.

emac_bd_rx_dequeue¶

int emac_bd_rx_dequeue(uint32_t flags, uint32_t *len, uint8_t *data_out);

Take the next received frame from the RX ring.

Copies the frame out of the current RX descriptor, hands the descriptor back to the EMAC and advances to the next one. Non-blocking.

參數	說明
`flags`	Ignored.
`len`	Received frame length in bytes; 0 when no frame is ready.
`data_out`	Destination buffer of at least `ETH_MAX_PACKET_SIZE` bytes, or NULL to drop the frame without copying.

回傳碼	說明
`0`	A frame was taken.
`NORESC`	No received frame is pending.

前置條件：emac_bd_init() has been called.

注意

No locking: call from one context only, and not together with the lwIP interface of hal_ethernetif.h.

emac_rx_done_callback_app¶

__WEAK void emac_rx_done_callback_app(void);

Application hook: a frame has been received.

Called from the EMAC interrupt handler only when CTX_TYPE is 0; with the default CTX_TYPE 1 the driver wakes its own task instead and this hook is not called. The RX-done interrupt is masked before the hook runs; unmask it with emac_intmask() once the RX ring has been drained. The driver supplies an empty weak default.

注意