FSPIM 驱动程序

1. 概述

• SPI 总线是一种4线总线，提供了一种高速、高效率的串行通信技术。SPI 通信通常有一个主设备和一个或多个从设备，需要至少4根线，它们是 MISO（主设备数据输入）、MOSI（主设备数据输出）、SCLK（时钟）、CS（片选）

• 其中，CS是从芯片是否被主芯片选中的控制信号，SCLK提供时钟脉冲，SDI，SDO则基于此脉冲完成数据传输

• 本驱动程序提供了FT2000/4、D2000平台的SPI主设备功能

• FT2000/4、D2000上包含 2 个通用 SPI 接口，仅作为通用 SPI 主设备使用，外部最多挂载 4 个 SPI 从设备

2. 功能

• 驱动相关的源文件如下，
• drivers/spi/fspim

.
├── fspim.c
├── fspim.h
├── fspim_g.c
├── fspim_hw.c
├── fspim_hw.h
├── fspim_intr.c
├── fspim_options.c
└── fspim_sinit.c

• FSPIM 常用于读写Nor-flash，其应用可以参考以下结构，最底层的硬件是 SPI 主机控制器和 Nor-flash, 其上由 FSPIM 驱动和 SFUD 提供 Spi Nor-flash的读写接口，面向SPI文件系统，如 LittleFS 和 SPIFFS，文件系统提供负载均衡、坏块检测和断电保护等特性，并为上层应用提供文件创建/读写等接口，使用方法参考4 应用示例

3. 配置方法

以下部分将指导您完成 FSPIM 驱动的软件配置:

3.1 使用 SFUD 通用SPI协议框架

• 使能 CONFIG_USE_FSPIM 和 CONFIG_USE_SFUD 配置
• 初始化 SFUD 框架
• 调用 SFUD 提供的 API 读写 SPI 从设备

关于 SFUD 框架的使用，可以参考sfud.md

3.2 不使用 SFUD 通用SPI协议框架

• 使能 CONFIG_USE_FSPIM 配置
• 初始 FSPIM 驱动
• 调用 FSPIM 提供的 API 读写 SPI 从设备，需要按照 SPI 从设备的手册实现相关的命令和协议

4 应用示例

SPI 测试

SPI Norflash读写测试

SPI Norflash文件系统测试-SPIFFS

4. API参考

4.1 用户数据结构

• SPIM 驱动配置数据

typedef struct
{
    u32                  instance_id;  /* Device instance id */
    uintptr              base_addr;    /* Device base address */
    u32                  irq_num;      /* Device interrupt id */
    u32                  irq_prority;  /* Device interrupt priority */    
    FSpimSlaveDevice     slave_dev_id; /* Slave device id */
    u32                  max_freq_hz;  /* Clock frequency in Hz */
    FSpimTransByte       n_bytes;      /* Bytes in transfer */
    FSpimCpolType        cpol;         /* Polarity of the clock */
    FSpimCphaType        cpha;         /* Phase of the clock */
    boolean              en_test;      /* Enable test mode */
} FSpimConfig;

• SPIM 驱动控制数据

typedef struct
{
    FSpimConfig         config;      /* Current active configs */
    u32                 is_ready;    /* Device is initialized and ready */
    u32                 length;      /* Data length in transfer */
    const void          *tx_buff;    /* Tx buffer beg */
    void                *rx_buff;    /* Rx buffer beg */
    const void          *tx_buff_end; /* Tx buffer end */
    void                *rx_buff_end; /* Rx buffer end */
    u32                 tx_fifo_len;  /* Depth of tx fifo */
    u32                 rx_fifo_len;  /* Depth of rx fifo */
    FSpimEvtHandler     evt_handler[FSPIM_INTR_EVT_NUM];  /* event handler for interrupt */
    void                *evt_param[FSPIM_INTR_EVT_NUM];   /* parameters ptr of event handler */
} FSpim;

• SPI 从设备ID，最多支持4个从设备

enum
{
    FSPIM_SLAVE_DEV_0 = 0,
    FSPIM_SLAVE_DEV_1,
    FSPIM_SLAVE_DEV_2,
    FSPIM_SLAVE_DEV_3,

    FSPIM_NUM_OF_SLAVE_DEV
};

• 一次 SPI 传输的数据量，一个字节或者两个字节

enum
{
    FSPIM_1_BYTE = 1,
    FSPIM_2_BYTE = 2,

    FSPIM_MAX_BYTES_NUM
};

• SPI传输，选择接收/发送

enum
{
    FSPIM_TRANS_MODE_RX_TX = 0x0,
    FSPIM_TRANS_MODE_TX_ONLY = 0x1,
    FSPIM_TRANS_MODE_RX_ONLY = 0x2,
    FSPIM_TRANS_MODE_READ_EEPROM = 0x3,

    FSPIM_TRANS_MODE_MAX
};

• SPI的时钟极性和相位

enum
{
    FSPIM_CPOL_LOW  = 0,
    FSPIM_CPOL_HIGH
};

enum
{
    FSPIM_CPHA_1_EDGE = 0,
    FSPIM_CPHA_2_EDGE
};

4.2 错误码定义

• 模块错误码编号：0x1060000
• [0x0] FSPIM_SUCCESS : fspim success
• [0x1060000] FSPIM_SUCCESS : fspim success
• [0x1060001] FSPIM_ERR_INVAL_STATE : fspim invalid state
• [0x1060002] FSPIM_ERR_NOT_READY : fspim driver not ready
• [0x1060003] FSPIM_ERR_INVAL_PARAM : fspim invalid input parameters
• [0x1060004] FSPIM_ERR_BUS_BUSY : fspim bus is busy
• [0x1060005] FSPIM_ERR_NOT_SUPPORT : fspim not support operation
• [0x1060006] FSPIM_ERR_TIMEOUT : fspim wait timeout

4.3 用户API接口

FSpimLookupConfig

• 获取FSPIM驱动的默认配置参数

const FSpimConfig *FSpimLookupConfig(u32 instance_id)

Note:

• 用户可以通过此接口获取驱动默认配置的副本，进行修改后，作为FSpimCfgInitialize函数的入参使用

Input:

• u32 instance_id, 选择的FSPIM控制器实例号

Return:

• const FSpimConfig *, 返回的默认驱动配置，返回NULL表示失败

FSpimCfgInitialize

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

FError FSpimCfgInitialize(FSpim *instance_p, const FSpimConfig *cofig_p);

Note:

• 此函数会重置FSPIM控制器和FSPIM控制数据

Input:

• FSpim *instance_p, FSPIM驱动控制数据

• const FSpimConfig *input_config_p, FSPIM驱动配置数据

Return:

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

FSpimDeInitialize

• 完成FSPIM驱动实例去初始化，之后不能使用

void FSpimDeInitialize(FSpim *instance_p)

Note:

• 此函数会重置FSPIM控制数据

Input:

• FSpim *instance_p, FSPIM驱动控制数据

Return:

无

FSpimTransferPollFifo

• 先发送后接收数据 (阻塞处理)，利用Fifo进行处理

FError FSpimTransferPollFifo(FSpim *instance_p, const void *tx_buf, void *rx_buf, fsize_t len);

Note:

• 使用此函数前需要确保FSPIM驱动初始化成功
• 从函数不会使用中断，会按照TX FIFO的深度进行传输，每次发送填满TX FIFO后触发发送/接收动作

Input:

• FSpim *instance_p, FSPIM驱动控制数据

• const void *tx_buf, 写缓冲区，可以为空，为空时表示只关注读数据，此时驱动会发送0xff读数据

• void *rx_buf, 读缓冲区, 可以为空，为空时表示值关注写数据，此时SPI总线上返回的数据会被抛弃

• fsize_t len, 进行传输的长度，如果tx_buf或者rx_buf不为空，则两个buf的长度必须为len

Return:

• FError, 驱动初始化的错误码信息，FSPIM_SUCCESS 表示数据交换成功，其它返回值表示交换失败

FSpimTransferByInterrupt

• 先发送后接收数据 (中断处理)，利用Fifo进行处理

FError FSpimTransferByInterrupt(FSpim *instance_p, const void *tx_buf, void *rx_buf, fsize_t len);

Note:

• 使用此函数前需要确保FSPIM驱动初始化成功
• 此函数会安装TX FIFO的深度进行传输，每次发送填满TX FIFO后在中断中处理发送/接收动作，用户需要注册FSPIM_INTR_EVT_RX_DONE事件，传输过程中用户处理其它任务，等待传输完成后从tx_buf和rx_buf中读数据

Input:

• FSpim *instance_p, FSPIM驱动控制数据

• const void *tx_buf, 写缓冲区，可以为空，为空时表示只关注读数据，此时驱动会发送0xff读数据

• void *rx_buf, 读缓冲区, 可以为空，为空时表示值关注写数据，此时SPI总线上返回的数据会被抛弃

• fsize_t len, 进行传输的长度，如果tx_buf或者rx_buf不为空，则两个buf的长度必须为len

Return:

• FError, 驱动初始化的错误码信息，FSPIM_SUCCESS 表示数据交换成功，其它返回值表示交换失败

FSpimInterruptHandler

• SPIM中断处理函数

void FSpimInterruptHandler(s32 vector, void *param);

Note:

• 此函数给用户注册在中断处理模块中，从而在中断触发时进行处理
• 使用此函数前，用户需要打开部分中断屏蔽位

Input:

• s32 vector, 中断向量号，此处不关心此参数

• void *param, 中断输入参数, 指向FSPIM的驱动控制实例

Return:

无

FSpimRegisterIntrruptHandler

• SPIM中断事件注册函数

void FSpimRegisterIntrruptHandler(FSpim *instance_p, u32 evt, FSpimEvtHandler handler, void *param)

Note:

• 此函数与FSpimInterruptHandler配套使用，为中断处理注册事件回调函数

Input:

• FSpim *instance_p, FSPIM驱动控制数据

• u32 evt, 中断事件号码，参考FSPIM_INTR_EVT_NUM

• FSpimEvtHandler handler, 中断事件回调函数

• void *param, 中断事件回调函数的入参，取决于中断事件回调函数的实现

Return:

无

FSpimErrorToMessage

• 获取FSPIM驱动错误码

const char *FSpimErrorToMessage(FError error);

Note:

无

Input:

• FError error, FSPIM模块错误码

Return:

const char *, FSPIM模块错误码对应的信息

FSpimSetChipSelection

• 获取FSPIM驱动错误码

void FSpimSetChipSelection(FSpim *instance_p, boolean on);

Note:

无

Input:

• {FSpim} *instance_p, 驱动控制数据
• {boolean} on, TRUE: 片选打开, FALSE: 片选关闭

Return:

• 无