spi

串行外设接口。 更多...

spi 的协作图:

结构体
struct	_xf_hal_spi_callback_t
	spi 的回调函数结构体。 更多...
struct	_xf_hal_spi_gpio_t
	spi 的引脚设置。 更多...
struct	_xf_hal_spi_config_t
	用于对接 SPI 设置的参数。 更多...

类型定义
typedef uint32_t	xf_spi_num_t
	spi 序号。
typedef void(*	xf_hal_spi_cb_t) (xf_spi_num_t spi_num, void *user_data)
	spi 回调函数原型。
typedef struct _xf_hal_spi_callback_t	xf_hal_spi_callback_t
	spi 的回调函数结构体。
typedef enum _xf_hal_spi_hosts_t	xf_hal_spi_hosts_t
	spi 的主从模式。
typedef enum _xf_hal_spi_bit_order_t	xf_hal_spi_bit_order_t
	spi 传输位顺序。
typedef enum _xf_hal_spi_mode_t	xf_hal_spi_mode_t
	spi 模式。
typedef enum _xf_hal_spi_data_width_t	xf_hal_spi_data_width_t
	spi 传输数据位宽。
typedef enum _xf_hal_spi_cmd_t	xf_hal_spi_cmd_t
	用于对接 spi 设置的命令。
typedef struct _xf_hal_spi_gpio_t	xf_hal_spi_gpio_t
	spi 的引脚设置。
typedef struct _xf_hal_spi_config_t	xf_hal_spi_config_t
	用于对接 SPI 设置的参数。

枚举
enum	_xf_hal_spi_hosts_t { _XF_HAL_SPI_HOSTS_BASE = 0 , XF_HAL_SPI_HOSTS_MASTER = _XF_HAL_SPI_HOSTS_BASE , XF_HAL_SPI_HOSTS_SLAVE , _XF_HAL_SPI_HOSTS_MAX }
	spi 的主从模式。 更多...
enum	_xf_hal_spi_bit_order_t { _XF_HAL_SPI_BIT_ORDER_BASE = 0 , XF_HAL_SPI_BIT_ORDER_LSB_FIRST = _XF_HAL_SPI_BIT_ORDER_BASE , XF_HAL_SPI_BIT_ORDER_MSB_FIRST , _XF_HAL_SPI_BIT_ORDER_MAX }
	spi 传输位顺序。 更多...
enum	_xf_hal_spi_mode_t {   _XF_HAL_SPI_MODE_BASE = 0 , XF_HAL_SPI_MODE_0 = _XF_HAL_SPI_MODE_BASE , XF_HAL_SPI_MODE_1 , XF_HAL_SPI_MODE_2 ,   XF_HAL_SPI_MODE_3 , _XF_HAL_SPI_MODE_MAX }
	spi 模式。 更多...
enum	_xf_hal_spi_data_width_t {   _XF_HAL_SPI_DATA_WIDTH_BASE = 0 , XF_HAL_SPI_DATA_WIDTH_8_BITS = _XF_HAL_SPI_DATA_WIDTH_BASE , XF_HAL_SPI_DATA_WIDTH_16_BITS , XF_HAL_SPI_DATA_WIDTH_32_BITS ,   _XF_HAL_SPI_DATA_WIDTH_MAX }
	spi 传输数据位宽。 更多...
enum	_xf_hal_spi_cmd_t {   XF_HAL_SPI_CMD_DEFAULT = 0x0 , XF_HAL_SPI_CMD_HOSTS = 0x1 << 0 , XF_HAL_SPI_CMD_ENABLE = 0x1 << 1 , XF_HAL_SPI_CMD_BIT_ORDER = 0x1 << 2 ,   XF_HAL_SPI_CMD_MODE = 0x1 << 3 , XF_HAL_SPI_CMD_DATA_WIDTH = 0x1 << 4 , XF_HAL_SPI_CMD_TIMEOUT = 0x1 << 5 , XF_HAL_SPI_CMD_SPEED = 0x1 << 6 ,   XF_HAL_SPI_CMD_GPIO = 0x1 << 7 , XF_HAL_SPI_CMD_PREV_CB = 0x1 << 8 , XF_HAL_SPI_CMD_POST_CB = 0x1 << 9 , XF_HAL_SPI_CMD_ALL = 0x7FFFFFFF }
	用于对接 spi 设置的命令。 更多...

函数
xf_err_t	xf_hal_spi_init (xf_spi_num_t spi_num, xf_hal_spi_hosts_t hosts, uint32_t speed)
	spi 初始化函数。
xf_err_t	xf_hal_spi_deinit (xf_spi_num_t spi_num)
	spi 反初始化函数。
xf_err_t	xf_hal_spi_enable (xf_spi_num_t spi_num)
	spi 启用函数。
xf_err_t	xf_hal_spi_disable (xf_spi_num_t spi_num)
	spi 禁用函数。
xf_err_t	xf_hal_spi_set_prev_cb (xf_spi_num_t spi_num, xf_hal_spi_cb_t callback, void *user_data)
	设置 spi 传输前回调。
xf_err_t	xf_hal_spi_set_post_cb (xf_spi_num_t spi_num, xf_hal_spi_cb_t callback, void *user_data)
	设置 spi 传输后回调。
xf_err_t	xf_hal_spi_set_gpio (xf_spi_num_t spi_num, const xf_hal_spi_gpio_t *spi_gpio)
	设置 spi 的输出 io。
xf_err_t	xf_hal_spi_set_bit_order (xf_spi_num_t spi_num, xf_hal_spi_bit_order_t bit_order)
	设置 spi 输出的字节序。
xf_err_t	xf_hal_spi_set_mode (xf_spi_num_t spi_num, xf_hal_spi_mode_t mode)
	设置 spi 模式。
xf_err_t	xf_hal_spi_set_data_width (xf_spi_num_t spi_num, xf_hal_spi_data_width_t data_width)
	设置 spi 的传输数据宽度。
xf_err_t	xf_hal_spi_set_speed (xf_spi_num_t spi_num, uint32_t speed)
	设置 spi 的传输速度。
int	xf_hal_spi_write (xf_spi_num_t spi_num, const uint8_t *buffer, uint32_t size, uint32_t timeout_ms)
	spi 写入数据函数。
int	xf_hal_spi_read (xf_spi_num_t spi_num, uint8_t *buffer, uint32_t size, uint32_t timeout_ms)
	spi 读取数据函数。

详细描述

串行外设接口。

类型定义说明

xf_spi_num_t

typedef uint32_t xf_spi_num_t

spi 序号。

在文件 xf_hal_spi.h 第 43 行定义.

xf_hal_spi_cb_t

typedef void(* xf_hal_spi_cb_t) (xf_spi_num_t spi_num, void *user_data)

spi 回调函数原型。

参数

spi_num	请求回调的 spi 序号。
user_data	用户数据，见 xf_hal_spi_set_prev_cb 或 xf_hal_spi_set_post_cb 的 user_data 参数。

在文件 xf_hal_spi.h 第 53 行定义.

xf_hal_spi_callback_t

typedef struct _xf_hal_spi_callback_t xf_hal_spi_callback_t

spi 的回调函数结构体。

xf_hal_spi_hosts_t

typedef enum _xf_hal_spi_hosts_t xf_hal_spi_hosts_t

spi 的主从模式。

xf_hal_spi_bit_order_t

typedef enum _xf_hal_spi_bit_order_t xf_hal_spi_bit_order_t

spi 传输位顺序。

xf_hal_spi_mode_t

typedef enum _xf_hal_spi_mode_t xf_hal_spi_mode_t

spi 模式。

每种模式由两个参数决定：时钟极性（CPOL）和时钟相位（CPHA）。

xf_hal_spi_data_width_t

typedef enum _xf_hal_spi_data_width_t xf_hal_spi_data_width_t

spi 传输数据位宽。

xf_hal_spi_cmd_t

typedef enum _xf_hal_spi_cmd_t xf_hal_spi_cmd_t

用于对接 spi 设置的命令。

注解

普通用户可忽略，移植者需注意。

xf_hal_spi_gpio_t

typedef struct _xf_hal_spi_gpio_t xf_hal_spi_gpio_t

spi 的引脚设置。

注解

普通用户可忽略，移植者需注意。

xf_hal_spi_config_t

typedef struct _xf_hal_spi_config_t xf_hal_spi_config_t

用于对接 SPI 设置的参数。

注解

普通用户可忽略，移植者需注意。

枚举类型说明

_xf_hal_spi_hosts_t

enum _xf_hal_spi_hosts_t

spi 的主从模式。

枚举值
_XF_HAL_SPI_HOSTS_BASE
XF_HAL_SPI_HOSTS_MASTER	主机模式
XF_HAL_SPI_HOSTS_SLAVE	从机模式
_XF_HAL_SPI_HOSTS_MAX

在文件 xf_hal_spi.h 第 66 行定义.

_xf_hal_spi_bit_order_t

enum _xf_hal_spi_bit_order_t

spi 传输位顺序。

枚举值
_XF_HAL_SPI_BIT_ORDER_BASE
XF_HAL_SPI_BIT_ORDER_LSB_FIRST	低位在前的传输方式
XF_HAL_SPI_BIT_ORDER_MSB_FIRST	高位在前的传输方式
_XF_HAL_SPI_BIT_ORDER_MAX

在文件 xf_hal_spi.h 第 78 行定义.

_xf_hal_spi_mode_t

enum _xf_hal_spi_mode_t

spi 模式。

每种模式由两个参数决定：时钟极性（CPOL）和时钟相位（CPHA）。

枚举值
_XF_HAL_SPI_MODE_BASE
XF_HAL_SPI_MODE_0	CPOL = 0, CPHA = 0
XF_HAL_SPI_MODE_1	CPOL = 0, CPHA = 1
XF_HAL_SPI_MODE_2	CPOL = 1, CPHA = 0
XF_HAL_SPI_MODE_3	CPOL = 1, CPHA = 1
_XF_HAL_SPI_MODE_MAX

在文件 xf_hal_spi.h 第 92 行定义.

_xf_hal_spi_data_width_t

enum _xf_hal_spi_data_width_t

spi 传输数据位宽。

枚举值
_XF_HAL_SPI_DATA_WIDTH_BASE
XF_HAL_SPI_DATA_WIDTH_8_BITS	spi 传输位宽为 8bit 数据
XF_HAL_SPI_DATA_WIDTH_16_BITS	spi 传输位宽为 16bit 数据
XF_HAL_SPI_DATA_WIDTH_32_BITS	spi 传输位宽为 32bit 数据
_XF_HAL_SPI_DATA_WIDTH_MAX

在文件 xf_hal_spi.h 第 106 行定义.

_xf_hal_spi_cmd_t

enum _xf_hal_spi_cmd_t

用于对接 spi 设置的命令。

注解

普通用户可忽略，移植者需注意。

枚举值
XF_HAL_SPI_CMD_DEFAULT	默认参数命令，在创建设备时优先执行
XF_HAL_SPI_CMD_HOSTS	主从命令，见 xf_hal_spi_config_t::hosts
XF_HAL_SPI_CMD_ENABLE	启用命令，见 xf_hal_spi_config_t::enable
XF_HAL_SPI_CMD_BIT_ORDER	字节序命令，见 xf_hal_spi_config_t::bit_order
XF_HAL_SPI_CMD_MODE	模式命令，见 xf_hal_spi_config_t::mode
XF_HAL_SPI_CMD_DATA_WIDTH	传输位宽命令，见 xf_hal_spi_config_t::data_width
XF_HAL_SPI_CMD_TIMEOUT	超时命令，见 xf_hal_spi_config_t::timeout_ms
XF_HAL_SPI_CMD_SPEED	速度命令，见 xf_hal_spi_config_t::speed
XF_HAL_SPI_CMD_GPIO	传输io命令，见 xf_hal_spi_config_t::gpio
XF_HAL_SPI_CMD_PREV_CB	传输前回调命令，见 xf_hal_spi_config_t::prev_cb
XF_HAL_SPI_CMD_POST_CB	传输后回调命令，见 xf_hal_spi_config_t::post_cb
XF_HAL_SPI_CMD_ALL	默认设置命令，在创建设备时其次执行

在文件 xf_hal_spi.h 第 121 行定义.

函数说明

xf_hal_spi_init()

xf_err_t xf_hal_spi_init	(	xf_spi_num_t	spi_num,
		xf_hal_spi_hosts_t	hosts,
		uint32_t	speed
	)

spi 初始化函数。

使用 spi 之前必须要进行初始化。

参数

spi_num	spi 的序号。
hosts	主从机模式。见 xf_hal_spi_hosts_t.
speed	传输速度。 单位为 hz

返回

xf_err_t

• XF_OK 成功初始化
• other 初始化失败

在文件 xf_hal_spi.c 第 50 行定义.

xf_hal_spi_deinit()

xf_err_t xf_hal_spi_deinit

(

xf_spi_num_t

spi_num

)

spi 反初始化函数。

恢复到未初始化状态且回收相关资源。

参数

spi_num

spi 的序号。

返回

xf_err_t

• XF_OK 成功反初始化
• XF_ERR_UNINIT 该 spi 未初始化
• other 反初始化失败

在文件 xf_hal_spi.c 第 77 行定义.

xf_hal_spi_enable()

xf_err_t xf_hal_spi_enable

(

xf_spi_num_t

spi_num

)

spi 启用函数。

spi 配置好功能后，可以调用 spi 启用函数进行激活。

注解

激活后，方可使用 xf_hal_spi_write 等函数。激活之前的配置是静态配置。

激活之后的配置属于动态配置，不一定所有的芯片都支持动态配置。

参数

spi_num

spi 的序号。

返回

xf_err_t

• XF_OK 成功启用
• XF_ERR_UNINIT 该 spi 未初始化
• other 启用失败

在文件 xf_hal_spi.c 第 92 行定义.

xf_hal_spi_disable()

xf_err_t xf_hal_spi_disable

(

xf_spi_num_t

spi_num

)

spi 禁用函数。

注解

如果 spi 正在启用状态，且不支持动态配置。则需要该函数， 先将 spi 禁用，然后进行配置。再次进行启用。

参数

spi_num

spi 的序号。

返回

xf_err_t

• XF_OK 成功禁用
• XF_ERR_UNINIT 该 spi 未初始化
• other 禁用失败

在文件 xf_hal_spi.c 第 117 行定义.

xf_hal_spi_set_prev_cb()

xf_err_t xf_hal_spi_set_prev_cb	(	xf_spi_num_t	spi_num,
		xf_hal_spi_cb_t	callback,
		void *	user_data
	)

设置 spi 传输前回调。

callback 会在传输开始前进行调用。

参数

spi_num	spi 的序号。
callback	传输前的回调函数。
user_data	用户自定义参数。

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 142 行定义.

xf_hal_spi_set_post_cb()

xf_err_t xf_hal_spi_set_post_cb	(	xf_spi_num_t	spi_num,
		xf_hal_spi_cb_t	callback,
		void *	user_data
	)

设置 spi 传输后回调。

callback 会在传输结束后进行调用。

参数

spi_num	spi 的序号。
callback	传输后的回调函数。
user_data	用户自定义参数。

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 168 行定义.

xf_hal_spi_set_gpio()

xf_err_t xf_hal_spi_set_gpio	(	xf_spi_num_t	spi_num,
		const xf_hal_spi_gpio_t *	spi_gpio
	)

设置 spi 的输出 io。

参数

spi_num	spi 的序号。
spi_gpio	spi 的 io 口，不需要的设置为 XF_HAL_GPIO_NUM_NONE。

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 194 行定义.

xf_hal_spi_set_bit_order()

xf_err_t xf_hal_spi_set_bit_order	(	xf_spi_num_t	spi_num,
		xf_hal_spi_bit_order_t	bit_order
	)

设置 spi 输出的字节序。

参数

spi_num	spi 的序号。
bit_order	spi 的字节序。见 xf_hal_spi_bit_order_t.

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 219 行定义.

xf_hal_spi_set_mode()

xf_err_t xf_hal_spi_set_mode	(	xf_spi_num_t	spi_num,
		xf_hal_spi_mode_t	mode
	)

设置 spi 模式。

与时钟极性（CPOL）和时钟相位（CPHA）有关

参数

spi_num	spi 的序号。
mode	spi 的模式。总共有四种。见 xf_hal_spi_mode_t.

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 244 行定义.

xf_hal_spi_set_data_width()

xf_err_t xf_hal_spi_set_data_width	(	xf_spi_num_t	spi_num,
		xf_hal_spi_data_width_t	data_width
	)

设置 spi 的传输数据宽度。

参数

spi_num	spi 的序号。
data_width	spi 传输数据的宽度。见 xf_hal_spi_data_width_t.

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 269 行定义.

xf_hal_spi_set_speed()

xf_err_t xf_hal_spi_set_speed	(	xf_spi_num_t	spi_num,
		uint32_t	speed
	)

设置 spi 的传输速度。

参数

spi_num	spi 的序号。
speed	spi 的传输速度，单位为 hz。

返回

xf_err_t

• XF_OK 成功设置
• XF_ERR_UNINIT 该 spi 未初始化
• other 设置失败

在文件 xf_hal_spi.c 第 294 行定义.

xf_hal_spi_write()

int xf_hal_spi_write	(	xf_spi_num_t	spi_num,
		const uint8_t *	buffer,
		uint32_t	size,
		uint32_t	timeout_ms
	)

spi 写入数据函数。

参数

spi_num	spi 的序号。
buffer	写入数据的指针。
size	写入数据的大小。
timeout_ms	超时时间，单位为ms（针对有RTOS的底层）。

返回

int 实际写入大小

在文件 xf_hal_spi.c 第 319 行定义.

xf_hal_spi_read()

int xf_hal_spi_read	(	xf_spi_num_t	spi_num,
		uint8_t *	buffer,
		uint32_t	size,
		uint32_t	timeout_ms
	)

spi 读取数据函数。

参数

spi_num	spi 的序号。
buffer	读取数据函数。
size	读取数据的大小。
timeout_ms	超时时间，单位为ms（针对有RTOS的底层）。

返回

int 实际读取大小

在文件 xf_hal_spi.c 第 350 行定义.