FXMAC 驱动程序

1. 概述

以太网控制器（XMAC）的主要功能是在兼容 IEEE802.3 standard 标准的以太网中发送和接收数据，当前支持 SGMII/RGMII 的 PHY 接口

XMAC 接口特点包括

支持速率 1000Mbps/100Mbps/10Mbps
支持 Reduced Gigabit Media Independent Interface (RGMII)
支持 SGMII Serial Gigabit Media-Independent Interface （SGMII）

2. 功能

XMAC 驱动提供了以太网控制器的初始化，DMA 环形队列使用函数，外部PHY 接口相关的配置功能

XMAC 驱动程序的源文件包括，

.
├── fxmac_bd.h
├── fxmac_bdring.c
├── fxmac_bdring.h
├── fxmac.c
├── fxmac_g.c
├── fxmac.h
├── fxmac_hw.h
├── fxmac_intr.c
├── fxmac_options.c
├── fxmac_phy.c
├── fxmac_phy.h
├── fxmac_sinit.c
├── Kconfig
└── phy
    ├── eth_ieee_reg.h
    └── yt
        ├── phy_yt.c
        └── phy_yt.h

其中fxmac.h/fxmac.c 为开发者提供以下功能：
mac 控制器实例初始化
设置每个控制器实例中4个mac地址的接口
设置每个控制器实例中4个mac匹配地址的接口
外置phy 芯片交互接口
中断相关接口
其中fxmac_bdring.h/fxmac_bdring.c 为开发者提供了以下功能：
创建dma 环形队列
环形队列数据拷贝
环形队列描述符分配
环形队列描述符释放

4 应用示例

fgmac_lwip_echo

启动LWIP网络协议栈，通过FXMAC驱动，支持开发板和网络主机的ping通

lwip port

fxmac 耦合lwip 功能

5. API参考

5.1. 用户数据结构

FXMAC 驱动配置数据

typedef struct
{
    u32 instance_id; /* Id of device*/
    volatile uintptr_t base_address;
    volatile uintptr_t extral_mode_base;
    volatile uintptr_t extral_loopback_base;
    FXmacPhyInterface interface; /* 接口类型，提供SGMII/RGMII 选择 */
    u32 speed;    /* FXMAC_SPEED_XXX */
    u32 duplex;   /* 1 is full-duplex , 0 is half-duplex */
    u32 auto_neg; /* Enable auto-negotiation - when set active high, autonegotiation operation is enabled. */
    u32 pclk_hz;
    u32 max_queue_num; /* Number of Xmac Controller Queues  */
    u32 tx_queue_id;   /* 0 ~ FT_XMAC_QUEUE_MAX_NUM ,Index queue number */
    u32 rx_queue_id;   /* 0 ~ FT_XMAC_QUEUE_MAX_NUM ,Index queue number */
    u32 hotplug_irq_num;
    u32 dma_brust_length; /*  burst length */
    u32 network_default_config; /* mac 控制器默认配置 */
    u32 queue_irq_num[FT_XMAC_QUEUE_MAX_NUM]; /* mac0 8个 ，其他的 4个 */
} FXmacConfig;

FGMAC 驱动控制数据

typedef struct
{
    FXmacConfig config;
    u32 is_ready; /* Device is ininitialized and ready*/
    u32 is_started; 
    u32 link_status; /* indicates link status ,FXMAC_LINKUP is link up ,FXMAC_LINKDOWN is link down,FXMAC_NEGOTIATING is need to negotiating*/
    u32 options;

    FXmacQueue tx_bd_queue; /* Transmit Queue */
    FXmacQueue rx_bd_queue; /* Receive Queue */

    FXmacIrqHandler send_irq_handler;
    void *send_args;

    FXmacIrqHandler recv_irq_handler;
    void *recv_args;

    FXmacErrorIrqHandler error_irq_handler;
    void *error_args;

    FXmacIrqHandler link_change_handler;
    void *link_change_args;

    FXmacIrqHandler restart_handler;
    void *restart_args;

    u32 moudle_id; /* Module identification number */
    u32 max_mtu_size;
    u32 max_frame_size;

    u32 phy_address;                    /* phy address */
    u32 rxbuf_mask; /* Filter length */ /* 1000,100,10 */

} FXmac;

FGMAC DMA描述符

typedef struct
{
    uintptr phys_base_addr; /* Physical address of 1st BD in list */
    uintptr base_bd_addr;   /* Virtual address of 1st BD in list */
    uintptr high_bd_addr;   /* Virtual address of last BD in the list */
    u32 length;             /* Total size of ring in bytes */
    u32 run_state;          /* Flag to indicate DMA is started */
    u32 separation;         /* Number of bytes between the starting address
                              of adjacent BDs */
    FXmacBd *free_head;
    /* First BD in the free group */
    FXmacBd *pre_head; /* First BD in the pre-work group */
    FXmacBd *hw_head;  /* First BD in the work group */
    FXmacBd *hw_tail;  /* Last BD in the work group */
    FXmacBd *post_head;
    /* First BD in the post-work group */
    FXmacBd *bda_restart;
    /* BDA to load when channel is started */

    volatile u32 hw_cnt; /* Number of BDs in work group */
    u32 pre_cnt;         /* Number of BDs in pre-work group */
    u32 free_cnt;        /* Number of allocatable BDs in the free group */
    u32 post_cnt;        /* Number of BDs in post-work group */
    u32 all_cnt;         /* Total Number of BDs for channel */
} FXmacBdRing;

FGMAC DMA描述符表(链式)相关数据

typedef struct
{
u32 desc_idx;       /* For Current Desc position */
u32 desc_buf_idx;   /* For Current Desc buffer buf position */
u32 desc_max_num;   /* Max Number for  Desc and Desc buffer */
u8 *desc_buf_base;  /*  Desc buffer Base */
} FGmacRingDescData;

5.2 错误码定义

模块错误码编号：0x1070000
[0x0] FGMAC: Success
FXMAC_ERR_INVALID_PARAM : Invalid parameter
FXMAC_ERR_SG_LIST : dma ring out of sequence
FXMAC_ERR_GENERAL :the number of BDs to allocate greater that the number of BDs in the preprocessing state.
FXMAC_ERR_SG_NO_LIST : dma ring is not allocated
FXMAC_ERR_PHY_BUSY : if there is another PHY operation in progress
FXMAC_PHY_IS_NOT_FOUND : phy is not found
FXMAC_PHY_AUTO_AUTONEGOTIATION_FAILED : PHY autonegotiation is error
FXMAC_ERR_MAC_IS_PROCESSING : MAC controllers are enabled together. As a result, some operations cannot be mirrored

5.3 初始化流程

FXmacLookupConfig 获取默认配置
修改默认配置中 phy interface 类型、协商模式
初始化mac 模块
初始化phy 模块
初始化mac 中断
初始化dma 模块
根据mac 默认配置启动mac 功能

5.4. 用户API接口

FXmacLookupConfig

获取FXMAC驱动的默认配置参数

const FXmacConfig *FXmacLookupConfig(u32 instance_id);

Note:

返回FXMAC的默认配置，复制后修改配置
需要确认当前平台支持输入的instance_id

Input:

{u32} instance_id, 驱动控制器号

Return:

{const FXmacConfig *}, 驱动默认配置

FXmacCfgInitialize

完成FGMAC驱动实例的初始化，使之可以使用

FError FXmacCfgInitialize(FXmac *instance_p, const FXmacConfig *config_p)

Note:

此函数会重置FGMAC控制器和FGMAC控制数据

Input:

{FXmac} *instance_p MAC 控制器实例指针
{FXmacConfig} *cofig_p 控制器驱动配置数据

Return:

{FError} 驱动初始化的错误码信息，FGMAC_SUCCESS 表示初始化成功，其它返回值表示初始化失败

FXmacInitInterface

根据phy 接口类型，初始化mac 控制器配置
```
void FXmacInitInterface(FXmac *instance_p)
```

Note:

此函数一般用于 PHY 芯片协商完成之后被调用，与PHY配置进行适配

Input:

{FXmac} *instance_p MAC 控制器实例指针

FXmacGetMacAddress

根据index 获取mac 地址

void FXmacGetMacAddress(FXmac *instance_p, u8 *address_ptr, u8 index)

Input :

{FGmac} *instance_p MAC 控制器实例指针
{u8} index MAC(0-3)地址的索引

Output :

{u8} *address_ptr 是指向缓冲区的指针当前MAC地址将被复制。

FXmacSetMacAddress

根据index 写入mac 地址

FError FXmacSetMacAddress(FXmac *instance_p, u8 *address_ptr, u8 index);

Input :

{FGmac} *instance_p MAC 控制器实例指针
{u8} *address_ptr 是指向缓冲区的指针当前MAC地址将被复制。
{u8} index MAC(0-3)地址的索引

Output :

{FError} FT_SUCCESS 如果MAC地址设置成功

FXmacSetOptions

设置FXmac 中的相关配置信息

FError FXmacSetOptions(FXmac *instance_p, u32 options, u32 queue_num)

Note:

必须在mac 控制器关闭的情况被调用

Input:

{FGmac} *instance_p MAC 控制器实例指针
{u32} options 是要设置的选项。选项参数位于 fxmac.h 中的 FXMAC_****_OPTION
{u32} queue_num mac控制器中队列的选项，仅在 FXMAC_JUMBO_ENABLE_OPTION 配置时被使用

Return:

{FError} FT_SUCCESS 设置成功

FXmacClearOptions

清除FXmac 中的相关配置信息

FError FXmacClearOptions(FXmac *instance_p, u32 options, u32 queue_num)

Note:

必须在mac 控制器关闭的情况被调用

Input:

{FGmac} *instance_p MAC 控制器实例指针
{u32} options 是要设置的选项。选项参数位于 fxmac.h 中的 FXMAC_****_OPTION
{u32} queue_num mac控制器中队列的选项，仅在 FXMAC_JUMBO_ENABLE_OPTION 配置时被使用

Return:

{FError} FT_SUCCESS 清除成功

FXmacStart

启动以太网控制器
```
void FXmacStart(FXmac *instance_p)
```

note:

根据 network_default_config 中的 FXMAC_TRANSMIT_ENABLE_OPTION 与 FXMAC_RECEIVER_ENABLE_OPTION ，决定是否开启控制器的接收与发送功能。并且默认开启接收与发送相关中断

Input:

{FGmac} *instance_p MAC 控制器实例指针

FXmacStop

关闭以太网控制器
```
void FXmacStop(FXmac *instance_p)
```

note:

关闭所有中断，关闭接收与发送功能

Input:

{FGmac} *instance_p MAC 控制器实例指针

FXmacSetQueuePtr

设置mac 控制器中接收/发送缓冲区的描述符环形队列的首地址

void FXmacSetQueuePtr(FXmac *instance_p, uintptr queue_p, u8 queue_num,
                  u32 direction)

Note:

描述符环形队列的首地址按照128bit 对其

Input:

{FXmac} *instance_p MAC 控制器实例指针
{uintptr} queue_p 写入队列的地址
{u8} queue_num 缓冲队列索引
{u32} direction 当为 FXMAC_SEND 表示方向为发送，当为 FXMAC_RECV 表示方向为接收

FXmacPhyWrite

将数据写入指定的PHY寄存器。

FError FXmacPhyWrite(FXmac *instance_p, u32 phy_address,
                 u32 register_num, u16 phy_data)

Note:

这个函数不是线程安全的。用户必须提供互斥的如果有多个线程可以调用该函数，则访问该函数。

Input:

{FXmac} *instance_p MAC 控制器实例指针
{u32} phy_address 要写入的PHY的地址
{u32} register_num 要写入的PHY的地址，特定PHY寄存器的寄存器号0-31
{u16} phy_data 需要写入对应PHY 芯片中对应register_num 的参数

Return:

{FError} FT_SUCCESS PHY 写入成功

FXmacPhyRead

指定PHY 芯片中对应的寄存器号，读出其中对应的参数

FError FXmacPhyRead(FXmac *instance_p, u32 phy_address,
                u32 register_num, u16 *phydat_aptr)

Note:

这个函数不是线程安全的。用户必须提供互斥的如果有多个线程可以调用该函数，则访问该函数。

Input:

{FXmac} *instance_p MAC 控制器实例指针
{u32} phy_address 要写入的PHY的地址
{u32} register_num 要写入的PHY的地址，特定PHY寄存器的寄存器号0-31

Output:

{u16} *phydat_aptr 需要读出对应PHY 芯片中对应register_num中值的指针

Return:

{FError} FT_SUCCESS PHY 读入成功

FXmacPhyInit

初始化PHY 芯片，首先检查出当前已连接的PHY 芯片地址，然后根据协商方式，确定
```
FError FXmacPhyInit(FXmac *instance_p, u32 speed,u32 duplex_mode, u32 autonegotiation_en);
```

Input:

{FXmac} *instance_p MAC 控制器实例指针
{u32} speed 需要设置的速度
{u32} duplex_mode 双工模式配置，1为全双工，0 为半双工
{u32} autonegotiation_en 为1 时，PHY 会进行自协商操作。为0时，将根据配置项进行协商

Return:

FError FT_SUCCESS 初始化成功

FXmacSelectClk

根据MAC 与 PHY 芯片连接的情况，设置相关时钟参数
```
void FXmacSelectClk(FXmac *instance_p )
```

Input:

{FXmac} *instance_p MAC 控制器实例指针

FXmacSetHandler

设置中断回调函数

FError FXmacSetHandler(FXmac *instance_p, u32 handler_type, void *func_pointer, void *call_back_ref)

Input:

{FXmac} *instance_p MAC 控制器实例指针
{u32} handler_type 指示中断处理程序类型 ,具体参数参考 FXMACHANDLER***
{void } *func_pointer 回调函数接口
{void } *call_back_ref 回调函数的传入参数

fxmac.md 13 KB Link permanente Histórico Em bruto

FXMAC 驱动程序

1. 概述

2. 功能

4 应用示例

fgmac_lwip_echo

lwip port

5. API参考

5.1. 用户数据结构

5.2 错误码定义

5.3 初始化流程

5.4. 用户API接口

FXmacLookupConfig

FXmacCfgInitialize

FXmacInitInterface

FXmacGetMacAddress

FXmacSetMacAddress

FXmacSetOptions

FXmacClearOptions

FXmacStart

FXmacStop

FXmacSetQueuePtr

FXmacPhyWrite

FXmacPhyRead

FXmacPhyInit

FXmacSelectClk

FXmacSetHandler

fxmac.md 13 KB

Link permanente Histórico Em bruto