Ethernet

[中文]

Overview

BK7258 integrates one 10/100M Ethernet MAC. It connects to an external PHY over the RMII interface and is registered as a standalone network interface in the lwIP stack. Key parameters:

Item	Description
MAC controller	Synopsys DWC_ether_qos, 10/100M
Register base	0x460a0000
Interface	RMII, fixed (not switchable)
Data valid signal	RXDV (CRS_DV is not used)
PHY device	SMSC LAN8710 / LAN8720
PHY address	Auto-scanned over MDIO, typically 1
Pin group	Two groups, selected at compile time via Kconfig
Tx descriptors	32
Rx descriptors	16
Rx buffers	1536 bytes x 24, 32-byte aligned, located in SRAM
Example project	projects/eth_example

The Ethernet driver lives in middleware/driver/eth/ and the lwIP porting layer in components/lwip_intf_v2_1/lwip-2.1.2/port/ethernetif.c. Both the AP and CP subsystems contain the full driver, but only one of them may own the Ethernet interface at a time.

Note

On BK7258, 0x48080000 is the base address of the DMA2D module, not Ethernet. Always confirm the base address when porting register access scripts from another platform.

1 Hardware Design

1.1 Reference Clock

The RMII interface requires a 50MHz reference clock (REF_CLK). This clock is supplied by board-level hardware; software does not generate it.

The SMSC LAN8710/LAN8720 has its own crystal (typically a 25MHz crystal or a 50MHz oscillator) and drives the 50MHz out of its REF_CLK pin to the MAC. The SoC side only does two things:

• Map the corresponding pin to GPIO_DEV_ENET_REF_CLK

• Enable the MAC module clock gate enet_cken

Consequently there is no software-configurable clock direction, PLL calibration value, lock wait or timing skew. Please verify the following in hardware design:

• The PHY crystal oscillates correctly at the frequency required by its datasheet

• The PHY straps are set so that it outputs the clock on the REF_CLK pin

• Keep the REF_CLK trace short; add a series resistor if necessary to avoid overshoot that would disturb MAC sampling

Important

A missing REF_CLK typically shows up as a MAC soft reset timeout, printing soft reset timeout in the log. MDIO usually still works in that case (MDC is generated by the MAC itself and does not depend on REF_CLK). When the PHY is readable but the soft reset fails, suspect REF_CLK first.

1.2 Pin Assignment

Two pin groups are available, selected at compile time by Kconfig and mapped at runtime in HAL_ETH_MspInit() via gpio_dev_map(). The signal-to-GPIO mapping is fixed and cannot be changed by the project.

Pin group 0 (CONFIG_ETH_PIN_GROUP0, default):

Signal	GPIO
ENET_PHY_INT	GPIO27
ENET_MDC	GPIO29
ENET_MDIO	GPIO32
ENET_RXD0	GPIO33
ENET_RXD1	GPIO34
ENET_RXDV	GPIO35
ENET_TXD0	GPIO36
ENET_TXD1	GPIO37
ENET_TXEN	GPIO38
ENET_REF_CLK	GPIO39

Pin group 1 (CONFIG_ETH_PIN_GROUP1):

Signal	GPIO
ENET_PHY_INT	GPIO46
ENET_MDC	GPIO47
ENET_MDIO	GPIO48
ENET_RXD0	GPIO49
ENET_RXD1	GPIO50
ENET_RXDV	GPIO51
ENET_TXD0	GPIO52
ENET_TXD1	GPIO53
ENET_TXEN	GPIO54
ENET_REF_CLK	GPIO55

Both groups share pads with other peripherals, so watch out for conflicts:

• The first alternate function of pin group 0 is JPEG_*, i.e. the DVP camera interface. These pads are also shared with TOUCH, SPI0, I2C1, PWM6-11 and SLCD. This group cannot be used when the DVP camera is enabled.

• Pin group 1 is shared with LCD functions and cannot be used when the LCD is enabled.

Note

Ethernet pins do not go through the project’s usr_gpio_cfg.h table. The mapping in HAL_ETH_MspInit() is hard coded, so changing pins requires editing ethernetif.c.

2 Configuration

2.1 Kconfig Options

Ethernet options are defined in middleware/driver/eth/Kconfig:

Option	Default	Description
CONFIG_ETH	n	Master switch for Ethernet
CONFIG_ETH_PIN_GROUP0	y	Use pin group 0 (GPIO27, 29, 32-39). Conflicts with DVP camera
CONFIG_ETH_PIN_GROUP1	n	Use pin group 1 (GPIO46-55). Conflicts with LCD
CONFIG_ETH_DHCP	n	Obtain IP via DHCP when enabled, static IP otherwise
CONFIG_ETH_CSUM_OFFLOAD	y	Offload IP/TCP/UDP/ICMP checksum to hardware
CONFIG_ETH_PM_CB_SUPPORT	n	Low power enter/exit callbacks. Also powers on the ETH domain
CONFIG_ETH_PTP	n	IEEE 1588-2008 precision time protocol
CONFIG_ETH_VLAN	n	VLAN support
CONFIG_ETH_TSO	n	TCP segmentation offload
CONFIG_ETH_LPI	n	Low power idle. Not supported by current hardware, keep disabled
CONFIG_ETH_EEE	n	Wake over LAN
CONFIG_ETH_REGISTER_CALLBACKS	n	Use the HAL callback registration mechanism
CONFIG_PHY_SMSC	y	SMSC 100M PHY driver (LAN8710/LAN8720)
CONFIG_PHY_MICREL_KSZ90X1	n	Micrel gigabit PHY driver
CONFIG_PHY_REALTEK	n	Realtek PHY driver

The minimal configuration to enable Ethernet:

CONFIG_ETH=y
CONFIG_ETH_PIN_GROUP0=y
CONFIG_PHY_SMSC=y
CONFIG_ETH_CSUM_OFFLOAD=y
CONFIG_ETH_PM_CB_SUPPORT=y

2.2 IP Address Configuration

How the IP address is obtained depends on CONFIG_ETH_DHCP. The defaults are in eth_ip_settings in components/lwip_intf_v2_1/lwip-2.1.2/port/net.c:

• CONFIG_ETH_DHCP enabled: address type is ADDR_TYPE_DHCP; DHCP starts automatically once the link is up

• Disabled: address type is ADDR_TYPE_STATIC; the static address in the structure is used

To change the static address, edit the address, gw, netmask and dns1 fields of eth_ip_settings. Note that these fields are in network byte order.

3 Getting Started

The SDK provides the projects/eth_example project. Build it with:

make bk7258 PROJECT=eth_example

The project itself contains no Ethernet application code; Ethernet is brought up automatically by bk_init(). After flashing, you should see PHY detection, link up and IP configuration logs in order:

netif st connected to SMSC LAN8710/LAN8720, mode rmii, phyad 1
ETH link up, speed 100M, Full-duplex
lwip:D(1740):eth ip start

Unplugging the cable prints the link down messages:

lwip:D(872619):ETH link down
lwip:D(872619):eth ip down

Note

eth_example currently enables CONFIG_ETH=y on the AP side only; the CP side is not enabled. CONFIG_ETH_DHCP is not enabled on the AP side either, so a static IP is used by default. Add CONFIG_ETH_DHCP=y to the AP configuration if DHCP is required.

4 Driver Implementation

4.1 Startup Call Chain

Ethernet is brought up synchronously during system initialization:

main()
└─ bk_init()
   └─ app_eth_init()
      └─ net_eth_start()
         ├─ miiphy_init()          Initialize the MDIO bus
         ├─ ieee8023_phy_init()    Register PHY drivers per Kconfig
         ├─ net_ipv4stack_init()   Initialize the TCP/IP stack
         ├─ net_eth_add_netif()    Register netif, triggers hardware init
         │  └─ ethernetif_init()
         │     └─ low_level_init()
         │        └─ HAL_ETH_Init()
         │           └─ HAL_ETH_MspInit()
         └─ Create the eth_link thread, polling link status every 200ms

Once the link goes up, the eth_link thread calls eth_ip_start() to configure the IP address.

Note

app_eth_init() neither checks the return value of net_eth_start() nor retries. If the hardware is not ready during initialization (for instance REF_CLK has not stabilized), Ethernet will not recover by itself and the application must implement its own retry.

4.2 Initialization Sequence

Main steps of low_level_init():

1. Allocate the private data structure eth_mac_priv

2. Fill heth: MAC address, HAL_ETH_RMII_MODE, descriptor tables and a receive buffer length of 1536

3. Call HAL_ETH_Init(), which triggers HAL_ETH_MspInit() on first call

4. Initialize the zero-copy receive pool RX_POOL

5. Set the netif hardware address, MTU and flags

6. PHY initialization: allocate and register the MDIO bus, call phy_connect() to scan for the PHY, then phy_config() and phy_startup()

7. Create the event queue and the EthIf thread

HAL_ETH_MspInit() performs low level initialization in this order:

1. Pin muxing: for the selected pin group, call gpio_dev_unmap() to release the previous function, then gpio_dev_map() to bind the ENET function

2. Power and sleep voting (CONFIG_ETH_PM_CB_SUPPORT): power on the ETH domain and forbid it from entering low power

3. MAC soft reset: write ETH_RESET_CTRL (at ETH_BASE + 0x802*4)

4. Enable the module clock: set enet_cken

5. Register the interrupt: register the INT_SRC_ETH handler and enable it

Important

HAL_ETH_MspInit() is guarded by if (heth->gState == HAL_ETH_STATE_RESET) and therefore runs at most once per boot. After a soft reset timeout gState becomes HAL_ETH_STATE_ERROR, so any later call to HAL_ETH_Init() only reissues the soft reset and does not remap pins, re-power the domain or re-enable the clock. To redo the full hardware initialization, restore gState to HAL_ETH_STATE_RESET manually first.

The MAC soft reset completes when the DMAMR.SWR bit self-clears. The timeout is defined by ETH_SWRESET_TIMEOUT as 500ms. This process requires a valid RMII reference clock.

4.3 PHY Management

The driver uses a multi-PHY framework. With CONFIG_ETH=y, smsc.c, realtek.c and micrel_ksz90x1.c are all compiled, but ieee8023_phy_init() only registers the drivers enabled in Kconfig. phy_connect() is called with a PHY address of -1, meaning it scans MDIO addresses 0 to 31 and matches the registered drivers against the PHY ID it reads.

PHY reset is performed over MDIO only (write BMCR_RESET then poll, up to 500ms). There is no GPIO hardware reset logic in the driver and no corresponding Kconfig option. If the hardware provides a PHY reset pin, the application must drive it.

The REF_CLK direction and RMII timing of the LAN8710/LAN8720 are both determined by hardware straps, and the driver has no registers for them. RMII timing problems can therefore only be addressed in hardware (strap resistors, trace length, series resistors).

5 Debug Commands

There are no Ethernet specific CLI commands. The generic network commands support the eth interface:

Command	Description
ip eth	Show or set the static IP of the Ethernet interface
ipconfig eth	Same as ip eth
mac	Show or set the Ethernet MAC address
ping <ip>	Connectivity test

6 FAQ

The link never comes up and the log shows soft reset timeout

The MAC soft reset did not complete within 500ms, which almost always means the RMII reference clock is missing. Probe the REF_CLK pin (GPIO39 for pin group 0, GPIO55 for pin group 1) for a stable 50MHz. Since software does not generate this clock, no signal means a hardware problem: the PHY crystal is not oscillating, the PHY is not powered, or the PHY straps configure it to expect a clock input.

No PHY is found during scanning

Check the pin muxing of MDC and MDIO, whether MDIO has a pull-up, and the PHY address straps. MDIO does not depend on REF_CLK, so an MDIO failure is unrelated to REF_CLK and should be traced through the MDIO wiring and pull-up.

Ethernet cannot work together with the camera or the display

Pin group 0 shares pads with the DVP camera and pin group 1 with the LCD. Choose the other group according to the peripherals in use, or adjust the hardware design.

The link is up but no traffic passes

Read registers layer by layer to narrow it down: check the OWN bit and the write-back error flags of the transmit descriptor to verify software delivery; check the queue packet count in MTL_TxQ0_Debug to see whether frames enter MTL and are fetched by the MAC; check whether Current_App_TxDesc and Current_App_RxDesc advance to see whether the DMA reclaims descriptors. Before relying on the MMC statistics registers, confirm in a known-good scenario that they really count.

No IP address is obtained

First check that CONFIG_ETH_DHCP matches your expectation. With the option disabled a static IP is used and no DHCP request is sent. If DHCP is enabled but no address arrives, inspect the interface with ip eth and confirm the link is up.