Crate fxmac_rs

Expand description

§FXMAC Ethernet Driver

A no_std Rust driver for the FXMAC Ethernet controller found on the PhytiumPi (Phytium Pi) board. This driver supports DMA-based packet transmission and reception, providing a foundation for network communication in embedded and bare-metal environments.

§Features

DMA Support: Efficient packet transmission and reception using DMA buffer descriptors.
PHY Management: Support for PHY initialization, auto-negotiation, and manual speed configuration.
Interrupt Handling: Built-in interrupt handlers for TX/RX completion and error conditions.
Multiple PHY Interfaces: Support for SGMII, RGMII, RMII, XGMII, and other interface modes.
Configurable: Supports jumbo frames, multicast filtering, and various MAC options.

§Target Platform

This driver is designed for the aarch64 architecture, specifically targeting the PhytiumPi board with the Motorcomm YT8521 PHY.

§Quick Start

To use this driver, you need to implement the KernelFunc trait to provide the necessary kernel functions for address translation and DMA memory allocation.

use fxmac_rs::{KernelFunc, xmac_init, FXmacLwipPortTx, FXmacRecvHandler};

// Implement the KernelFunc trait for your platform
pub struct FXmacDriver;

#[crate_interface::impl_interface]
impl KernelFunc for FXmacDriver {
    fn virt_to_phys(addr: usize) -> usize {
        // Your implementation
        addr
    }

    fn phys_to_virt(addr: usize) -> usize {
        // Your implementation
        addr
    }

    fn dma_alloc_coherent(pages: usize) -> (usize, usize) {
        // Your implementation: returns (virtual_addr, physical_addr)
        unimplemented!()
    }

    fn dma_free_coherent(vaddr: usize, pages: usize) {
        // Your implementation
    }

    fn dma_request_irq(irq: usize, handler: fn()) {
        // Your implementation
    }
}

// Initialize the driver
let hwaddr: [u8; 6] = [0x55, 0x44, 0x33, 0x22, 0x11, 0x00];
let fxmac = xmac_init(&hwaddr);

// Send packets
let mut tx_vec = Vec::new();
tx_vec.push(packet_data.to_vec());
FXmacLwipPortTx(fxmac, tx_vec);

// Receive packets
if let Some(recv_packets) = FXmacRecvHandler(fxmac) {
    for packet in recv_packets {
        // Process received packet
    }
}

§Module Structure

[fxmac]: Core MAC controller functionality and configuration.
[fxmac_dma]: DMA buffer descriptor management and packet handling.
[fxmac_intr]: Interrupt handling and callback management.
[fxmac_phy]: PHY initialization and management functions.

§Safety and Environment

This crate targets no_std and assumes the platform provides DMA-coherent memory and interrupt routing.
Most APIs interact with memory-mapped registers and should be used with care in the correct execution context.

§Feature Flags

debug: Enable logging via the log crate. Without this feature, logging macros become no-ops.

Structs§

FXmac: Main FXMAC Ethernet controller instance.
FXmacBdRing
FXmacConfig: Hardware configuration for the FXMAC controller.
FXmacLwipPort
FXmacNetifBuffer
FXmacQueue: Hardware queue structure for TX/RX operations.
macb_dma_desc: DMA address width 64 bits: word 0: 32 bit address of Data Buffer word 1: control / status, 32-bit word 2: upper 32 bit address of Data Buffer word 3: unused

Enums§

FXmacPhyInterface: PHY interface mode definitions.

Constants§

BD_ALIGNMENT: Byte alignment of BDs
FT_COMPONENT_IS_READY: Component is initialized and ready.
FT_COMPONENT_IS_STARTED: Component is started.
FXMAC0_HOTPLUG_IRQ_NUM: FXMAC0 hotplug IRQ number.
FXMAC0_PCLK: FXMAC0 peripheral clock frequency in Hz.
FXMAC_BD_ADDR_HI_OFFSET: word 2/addr of BDs
FXMAC_BD_ADDR_OFFSET: Transmit buffer descriptor status words offset word 0/addr of BDs
FXMAC_BD_NUM_WORDS
FXMAC_BD_STAT_OFFSET: word 1/status of BDs, 4 bytes
FXMAC_DMABD_MINIMUM_ALIGNMENT
FXMAC_HANDLER_DMARECV: Handler type for DMA receive (RX) interrupts.
FXMAC_HANDLER_DMASEND: Handler type for DMA send (TX) interrupts.
FXMAC_HANDLER_ERROR: Handler type for error interrupts.
FXMAC_HANDLER_LINKCHANGE: Handler type for link status change interrupts.
FXMAC_HANDLER_RESTART: Handler type for TX descriptor queue restart.
FXMAC_LINKDOWN: Link status: down.
FXMAC_LINKUP: Link status: up.
FXMAC_LWIP_PORT_CONFIG_CLOSE_FCS_CHECK
FXMAC_LWIP_PORT_CONFIG_COPY_ALL_FRAMES
FXMAC_LWIP_PORT_CONFIG_JUMBO
FXMAC_LWIP_PORT_CONFIG_MULTICAST_ADDRESS_FILITER
FXMAC_LWIP_PORT_CONFIG_UNICAST_ADDRESS_FILITER
FXMAC_NEGOTIATING: Link status: negotiating.
FXMAC_PHY_FULL_DUPLEX
FXMAC_PHY_HALF_DUPLEX
FXMAC_PHY_SPEED_10G
FXMAC_PHY_SPEED_10M
FXMAC_PHY_SPEED_100M
FXMAC_PHY_SPEED_1000M
FXMAC_QUEUE_MAX_NUM: Maximum number of hardware queues supported.
FXMAC_RECV: receive direction
FXMAC_RECV_MAX_COUNT
FXMAC_RXBUF_ADD_MASK: Mask for address
FXMAC_RXBUF_NEW_MASK: RX Used bit
FXMAC_RXBUF_WRAP_MASK: RX Wrap bit, last BD
FXMAC_SEND: send direction
FXMAC_TXBUF_USED_MASK: TX Used bit
FXMAC_TXBUF_WRAP_MASK: TX Wrap bit, last descriptor
FXMAX_MAX_HARDWARE_ADDRESS_LENGTH
FXMAX_RX_BDSPACE_LENGTH
FXMAX_RX_PBUFS_LENGTH
FXMAX_TX_BDSPACE_LENGTH
FXMAX_TX_PBUFS_LENGTH
PAGE_SIZE: Memory page size in bytes.
PQ_QUEUE_SIZE
ULONG64_HI_MASK: Mask for upper 32 bits of 64-bit address.
ULONG64_LO_MASK: Mask for lower 32 bits of 64-bit address.

Traits§

KernelFunc: Kernel function interface required by the FXMAC Ethernet driver.

Functions§

FXmacAllocDmaPbufs
FXmacBdRingAlloc: 在BD list中预留待设置的BD
FXmacBdRingClone: 将给定的BD, 克隆到list中的每个BD上
FXmacBdRingCreate: Create the RxBD ring 创建收包的环形缓冲区
FXmacBdRingFree: FXmacBdRingFree, Frees a set of BDs that had been previously retrieved with
FXmacBdRingFromHwRx
FXmacBdRingFromHwTx: @name: FXmacBdRingFromHwTx @msg: Returns a set of BD(s) that have been processed by hardware. The returned BDs may be examined to determine the outcome of the DMA transaction(s). Once the BDs have been examined, the user must call FXmacBdRingFree() in the same order which they were retrieved here.
FXmacBdRingToHw: 将一组BD排队到之前由FXmacBdRingAlloc分配了的硬件上
FXmacGetMacAddress: Reads a MAC address from the specified address slot.
FXmacHandleDmaTxError: Handle DMA interrupt error
FXmacHandleTxErrors
FXmacInitDma
FXmacIntrHandler: Main interrupt handler for FXMAC controller.
FXmacLinkChange
FXmacLwipPortTx: Transmits packets through the lwIP-compatible interface.
FXmacPhyInit: Initializes the PHY for the FXMAC controller.
FXmacPhyRead: Reads data from a PHY register via MDIO.
FXmacPhyWrite: Writes data to a PHY register via MDIO.
FXmacProcessSentBds: FXmacProcessSentBds, 释放发送队列q参数
FXmacRecvHandler: Handles received packets from the DMA queue.
FXmacSendHandler
FXmacSetMacAddress: Sets the MAC address for the specified address slot.
FXmacSetQueuePtr: Sets the start address of the transmit/receive buffer queue.
FXmacSgsend: Transmits packets using scatter-gather DMA.
FXmacStart: Starts the Ethernet controller.
FXmacStop: Gracefully stops the Ethernet MAC.
FXmac_DeleteHash: Delete 48-bit MAC addresses in hash table. The device must be stopped before calling this function.
FXmac_SetHash: Sets a 48-bit MAC address entry in the hash table.
ResetDma: Reset Tx and Rx DMA pointers after FXmacStop
SetupRxBds
ethernetif_input_to_recv_packets
fxmac_bd_read
fxmac_bd_write
phy_autoneg_status
phy_link_detect: @name: phy_link_detect @msg: 获取当前link status @note: @param {FXmac} fxmac_p @param {u32} phy_addr @return {} 1 is link up , 0 is link down
read_reg: Reads a memory-mapped register via a physical address.
write_reg: Writes a value to a memory-mapped register via a physical address.
xmac_init: Initializes the FXMAC Ethernet controller.
xmac_intr_handler: Top-level interrupt handler for FXMAC.

Type Aliases§

FXmacBd
uintptr

Crate fxmac_rs

Crate fxmac_rs Copy item path

§FXMAC Ethernet Driver

§Features

§Target Platform

§Quick Start

§Module Structure

§Safety and Environment

§Feature Flags

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate fxmac_rs