SPI

SPI 的协作图:

结构体
struct	rt_spi_message
struct	rt_spi_configuration
struct	rt_spi_bus
struct	rt_spi_ops
struct	rt_spi_device
struct	rt_qspi_message
struct	rt_qspi_configuration
struct	rt_qspi_device

宏定义
#define	RT_SPI_CPHA   (1<<0)
#define	RT_SPI_CPOL   (1<<1)
#define	RT_SPI_LSB   (0<<2)
#define	RT_SPI_MSB   (1<<2)
#define	RT_SPI_MASTER   (0<<3)
#define	RT_SPI_SLAVE   (1<<3)
#define	RT_SPI_CS_HIGH   (1<<4)
#define	RT_SPI_NO_CS   (1<<5)
#define	RT_SPI_3WIRE   (1<<6)
#define	RT_SPI_READY   (1<<7)
#define	RT_SPI_MODE_MASK   (RT_SPI_CPHA | RT_SPI_CPOL | RT_SPI_MSB | RT_SPI_SLAVE | RT_SPI_CS_HIGH | RT_SPI_NO_CS | RT_SPI_3WIRE | RT_SPI_READY)
#define	RT_SPI_MODE_0   (0 | 0)
#define	RT_SPI_MODE_1   (0 | RT_SPI_CPHA)
#define	RT_SPI_MODE_2   (RT_SPI_CPOL | 0)
#define	RT_SPI_MODE_3   (RT_SPI_CPOL | RT_SPI_CPHA)
#define	RT_SPI_BUS_MODE_SPI   (1<<0)
#define	RT_SPI_BUS_MODE_QSPI   (1<<1)
#define	SPI_DEVICE(dev)

函数
rt_err_t	rt_spi_bus_register (struct rt_spi_bus *bus, const char *name, const struct rt_spi_ops *ops)
rt_err_t	rt_spi_bus_attach_device (struct rt_spi_device *device, const char *name, const char *bus_name, void *user_data)
rt_err_t	rt_spi_bus_attach_device_cspin (struct rt_spi_device *device, const char *name, const char *bus_name, rt_base_t cs_pin, void *user_data)
rt_err_t	rt_spi_bus_configure (struct rt_spi_device *device)
rt_err_t	rt_spi_take_bus (struct rt_spi_device *device)
rt_err_t	rt_spi_release_bus (struct rt_spi_device *device)
rt_err_t	rt_spi_take (struct rt_spi_device *device)
rt_err_t	rt_spi_release (struct rt_spi_device *device)
rt_err_t	rt_spi_configure (struct rt_spi_device *device, struct rt_spi_configuration *cfg)
rt_err_t	rt_spi_send_then_recv (struct rt_spi_device *device, const void *send_buf, rt_size_t send_length, void *recv_buf, rt_size_t recv_length)
rt_err_t	rt_spi_send_then_send (struct rt_spi_device *device, const void *send_buf1, rt_size_t send_length1, const void *send_buf2, rt_size_t send_length2)
rt_ssize_t	rt_spi_transfer (struct rt_spi_device *device, const void *send_buf, void *recv_buf, rt_size_t length)
rt_err_t	rt_spi_sendrecv8 (struct rt_spi_device *device, rt_uint8_t senddata, rt_uint8_t *recvdata)
rt_err_t	rt_spi_sendrecv16 (struct rt_spi_device *device, rt_uint16_t senddata, rt_uint16_t *recvdata)
struct rt_spi_message *	rt_spi_transfer_message (struct rt_spi_device *device, struct rt_spi_message *message)
rt_inline rt_size_t	rt_spi_recv (struct rt_spi_device *device, void *recv_buf, rt_size_t length)
rt_inline rt_size_t	rt_spi_send (struct rt_spi_device *device, const void *send_buf, rt_size_t length)
rt_inline void	rt_spi_message_append (struct rt_spi_message *list, struct rt_spi_message *message)
rt_err_t	rt_qspi_configure (struct rt_qspi_device *device, struct rt_qspi_configuration *cfg)
rt_err_t	rt_qspi_bus_register (struct rt_spi_bus *bus, const char *name, const struct rt_spi_ops *ops)
rt_size_t	rt_qspi_transfer_message (struct rt_qspi_device *device, struct rt_qspi_message *message)
rt_err_t	rt_qspi_send_then_recv (struct rt_qspi_device *device, const void *send_buf, rt_size_t send_length, void *recv_buf, rt_size_t recv_length)
rt_err_t	rt_qspi_send (struct rt_qspi_device *device, const void *send_buf, rt_size_t length)

详细描述

SPI driver api

Example

#include <rtthread.h>
#include <rtdevice.h>
 
#define W25Q_SPI_DEVICE_NAME     "qspi10"
 
static void spi_w25q_sample(int argc, char *argv[])
{
    struct rt_spi_device *spi_dev_w25q;
    char name[RT_NAME_MAX];
    rt_uint8_t w25x_read_id = 0x90;
    rt_uint8_t id[5] = {0};
 
    if (argc == 2)
    {
        rt_strncpy(name, argv[1], RT_NAME_MAX);
    }
    else
    {
        rt_strncpy(name, W25Q_SPI_DEVICE_NAME, RT_NAME_MAX);
    }
 
    // 查找 spi 设备获取设备句柄
    spi_dev_w25q = (struct rt_spi_device *)rt_device_find(name);
    if (!spi_dev_w25q)
    {
        rt_kprintf("spi sample run failed! can't find %s device!\n", name);
    }
    else
    {
        // 方式1：使用 rt_spi_send_then_recv()发送命令读取ID
        rt_spi_send_then_recv(spi_dev_w25q, &w25x_read_id, 1, id, 5);
        rt_kprintf("use rt_spi_send_then_recv() read w25q ID is:%x%x\n", id[3], id[4]);
 
        // 方式2：使用 rt_spi_transfer_message()发送命令读取ID
        struct rt_spi_message msg1, msg2;
 
        msg1.send_buf   = &w25x_read_id;
        msg1.recv_buf   = RT_NULL;
        msg1.length     = 1;
        msg1.cs_take    = 1;
        msg1.cs_release = 0;
        msg1.next       = &msg2;
 
        msg2.send_buf   = RT_NULL;
        msg2.recv_buf   = id;
        msg2.length     = 5;
        msg2.cs_take    = 0;
        msg2.cs_release = 1;
        msg2.next       = RT_NULL;
 
        rt_spi_transfer_message(spi_dev_w25q, &msg1);
        rt_kprintf("use rt_spi_transfer_message() read w25q ID is:%x%x\n", id[3], id[4]);
 
    }
}
// 导出到 msh 命令列表中
MSH_CMD_EXPORT(spi_w25q_sample, spi w25q sample);

宏定义说明

RT_SPI_CPHA

#define RT_SPI_CPHA   (1<<0)

At CPOL=0 the base value of the clock is zero

• For CPHA=0, data are captured on the clock's rising edge (low->high transition) and data are propagated on a falling edge (high->low clock transition).
• For CPHA=1, data are captured on the clock's falling edge and data are propagated on a rising edge. At CPOL=1 the base value of the clock is one (inversion of CPOL=0)
• For CPHA=0, data are captured on clock's falling edge and data are propagated on a rising edge.
• For CPHA=1, data are captured on clock's rising edge and data are propagated on a falling edge. bit[0]:CPHA, clock phase

在文件 dev_spi.h 第 111 行定义.

RT_SPI_CPOL

#define RT_SPI_CPOL   (1<<1)

bit[1]:CPOL, clock polarity

在文件 dev_spi.h 第 112 行定义.

RT_SPI_LSB

#define RT_SPI_LSB   (0<<2)

bit[2]: 0-LSB

在文件 dev_spi.h 第 114 行定义.

RT_SPI_MSB

#define RT_SPI_MSB   (1<<2)

bit[2]: 1-MSB

在文件 dev_spi.h 第 115 行定义.

RT_SPI_MASTER

#define RT_SPI_MASTER   (0<<3)

SPI master device

在文件 dev_spi.h 第 117 行定义.

RT_SPI_SLAVE

#define RT_SPI_SLAVE   (1<<3)

SPI slave device

在文件 dev_spi.h 第 118 行定义.

RT_SPI_CS_HIGH

#define RT_SPI_CS_HIGH   (1<<4)

Chipselect active high

在文件 dev_spi.h 第 120 行定义.

RT_SPI_NO_CS

#define RT_SPI_NO_CS   (1<<5)

No chipselect

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

RT_SPI_3WIRE

#define RT_SPI_3WIRE   (1<<6)

SI/SO pin shared

在文件 dev_spi.h 第 122 行定义.

RT_SPI_READY

#define RT_SPI_READY   (1<<7)

Slave pulls low to pause

在文件 dev_spi.h 第 123 行定义.

RT_SPI_MODE_MASK

#define RT_SPI_MODE_MASK   (RT_SPI_CPHA | RT_SPI_CPOL | RT_SPI_MSB | RT_SPI_SLAVE | RT_SPI_CS_HIGH | RT_SPI_NO_CS | RT_SPI_3WIRE | RT_SPI_READY)

在文件 dev_spi.h 第 125 行定义.

RT_SPI_MODE_0

#define RT_SPI_MODE_0   (0 | 0)

CPOL = 0, CPHA = 0

在文件 dev_spi.h 第 127 行定义.

RT_SPI_MODE_1

#define RT_SPI_MODE_1   (0 | RT_SPI_CPHA)

CPOL = 0, CPHA = 1

在文件 dev_spi.h 第 128 行定义.

RT_SPI_MODE_2

#define RT_SPI_MODE_2   (RT_SPI_CPOL | 0)

CPOL = 1, CPHA = 0

在文件 dev_spi.h 第 129 行定义.

RT_SPI_MODE_3

#define RT_SPI_MODE_3   (RT_SPI_CPOL | RT_SPI_CPHA)

CPOL = 1, CPHA = 1

在文件 dev_spi.h 第 130 行定义.

RT_SPI_BUS_MODE_SPI

#define RT_SPI_BUS_MODE_SPI   (1<<0)

在文件 dev_spi.h 第 132 行定义.

RT_SPI_BUS_MODE_QSPI

#define RT_SPI_BUS_MODE_QSPI   (1<<1)

在文件 dev_spi.h 第 133 行定义.

SPI_DEVICE

#define SPI_DEVICE

(

dev

)

值:

((struct rt_spi_device *)(dev))

在文件 dev_spi.h 第 291 行定义.

函数说明

rt_spi_bus_register()

rt_err_t rt_spi_bus_register	(	struct rt_spi_bus *	bus,
		const char *	name,
		const struct rt_spi_ops *	ops )

register a SPI bus

参数

bus	the SPI bus
name	the name of SPI bus
ops	the operations of SPI bus

返回

rt_err_t error code

rt_spi_bus_attach_device()

rt_err_t rt_spi_bus_attach_device	(	struct rt_spi_device *	device,
		const char *	name,
		const char *	bus_name,
		void *	user_data )

attach a device on SPI bus

参数

device	the SPI device
name	the name of SPI device
bus_name	the name of SPI bus
user_data	the user data of SPI device

返回

rt_err_t error code

rt_spi_bus_attach_device_cspin()

rt_err_t rt_spi_bus_attach_device_cspin	(	struct rt_spi_device *	device,
		const char *	name,
		const char *	bus_name,
		rt_base_t	cs_pin,
		void *	user_data )

attach a device on SPI bus with CS pin

参数

device	the SPI device
name	the name of SPI device
bus_name	the name of SPI bus
cs_pin	the CS pin of SPI device
user_data	the user data of SPI device

返回

rt_err_t error code

rt_spi_bus_configure()

rt_err_t rt_spi_bus_configure

(

struct rt_spi_device *

device

)

Reconfigure the SPI bus for the specified device.

参数

device

Pointer to the SPI device attached to the SPI bus.

返回值

RT_EOK

if the SPI device was successfully released and the bus was configured. RT_EBUSY if the SPI bus is currently in use; the new configuration will take effect once the device releases the bus. Other return values indicate failure to configure the SPI bus due to various reasons.

注解

If the configuration of the SPI device has been updated and requires bus re-initialization, call this function directly. This function will reconfigure the SPI bus for the specified device. If this is the first time to initialize the SPI device, please call rt_spi_configure or rt_qspi_configure. This function is used to reconfigure the SPI bus when the SPI device is already in use. For further details, refer to: https://github.com/RT-Thread/rt-thread/pull/8528

rt_spi_take_bus()

rt_err_t rt_spi_take_bus

(

struct rt_spi_device *

device

)

This function takes SPI bus.

参数

device

the SPI device attached to SPI bus

返回

RT_EOK on taken SPI bus successfully. others on taken SPI bus failed.

rt_spi_release_bus()

rt_err_t rt_spi_release_bus

(

struct rt_spi_device *

device

)

This function releases SPI bus.

参数

device

the SPI device attached to SPI bus

返回

RT_EOK on release SPI bus successfully.

rt_spi_take()

rt_err_t rt_spi_take

(

struct rt_spi_device *

device

)

This function take SPI device (takes CS of SPI device).

参数

device

the SPI device attached to SPI bus

返回

RT_EOK on release SPI bus successfully. others on taken SPI bus failed.

rt_spi_release()

rt_err_t rt_spi_release

(

struct rt_spi_device *

device

)

This function releases SPI device (releases CS of SPI device).

参数

device

the SPI device attached to SPI bus

返回

RT_EOK on release SPI device successfully.

rt_spi_configure()

rt_err_t rt_spi_configure	(	struct rt_spi_device *	device,
		struct rt_spi_configuration *	cfg )

This function can set configuration on SPI device.

参数

device	the SPI device attached to SPI bus
cfg	the configuration pointer.

返回值

RT_EOK

on release SPI device successfully. RT_EBUSY is not an error condition and the configuration will take effect once the device has the bus others on taken SPI bus failed.

rt_spi_send_then_recv()

rt_err_t rt_spi_send_then_recv	(	struct rt_spi_device *	device,
		const void *	send_buf,
		rt_size_t	send_length,
		void *	recv_buf,
		rt_size_t	recv_length )

This function can send data then receive data from SPI device.

参数

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
send_length	the number of data to be transmitted.
recv_buf	the buffer to be recivied from SPI device.
recv_length	the data to be recivied.

返回

rt_err_t error code

rt_spi_send_then_send()

rt_err_t rt_spi_send_then_send	(	struct rt_spi_device *	device,
		const void *	send_buf1,
		rt_size_t	send_length1,
		const void *	send_buf2,
		rt_size_t	send_length2 )

This function can send data then send data from SPI device.

参数

device	the SPI device attached to SPI bus
send_buf1	the buffer to be transmitted to SPI device.
send_length1	the number of data to be transmitted.
send_buf2	the buffer to be transmitted to SPI device.
send_length2	the number of data to be transmitted.

返回

the status of transmit.

rt_spi_transfer()

rt_ssize_t rt_spi_transfer	(	struct rt_spi_device *	device,
		const void *	send_buf,
		void *	recv_buf,
		rt_size_t	length )

This function transmits data to SPI device.

参数

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
recv_buf	the buffer to save received data from SPI device.
length	the length of transmitted data.

返回

the actual length of transmitted.

这是这个函数的调用关系图:

rt_spi_sendrecv8()

rt_err_t rt_spi_sendrecv8	(	struct rt_spi_device *	device,
		rt_uint8_t	senddata,
		rt_uint8_t *	recvdata )

The SPI device transmits 8 bytes of data

参数

device	the SPI device attached to SPI bus
senddata	send data buffer
recvdata	receive data buffer

返回

rt_err_t error code

rt_spi_sendrecv16()

rt_err_t rt_spi_sendrecv16	(	struct rt_spi_device *	device,
		rt_uint16_t	senddata,
		rt_uint16_t *	recvdata )

The SPI device transmits 16 bytes of data

参数

device	the SPI device attached to SPI bus
senddata	send data buffer
recvdata	receive data buffer

返回

rt_err_t error code

rt_spi_transfer_message()

struct rt_spi_message * rt_spi_transfer_message	(	struct rt_spi_device *	device,
		struct rt_spi_message *	message )

This function transfers a message list to the SPI device.

参数

device	the SPI device attached to SPI bus
message	the message list to be transmitted to SPI device

返回

RT_NULL if transmits message list successfully, SPI message which be transmitted failed.

rt_spi_recv()

rt_inline rt_size_t rt_spi_recv	(	struct rt_spi_device *	device,
		void *	recv_buf,
		rt_size_t	length )

This function receives data from SPI device.

参数

device	the SPI device attached to SPI bus
recv_buf	the buffer to be recivied from SPI device.
length	the data to be recivied.

返回

the actual length of received.

在文件 dev_spi.h 第 527 行定义.

{
    return rt_spi_transfer(device, RT_NULL, recv_buf, length);
}

引用了 rt_spi_message::length, rt_spi_message::recv_buf, RT_NULL , 以及 rt_spi_transfer().

函数调用图:

rt_spi_send()

rt_inline rt_size_t rt_spi_send	(	struct rt_spi_device *	device,
		const void *	send_buf,
		rt_size_t	length )

This function sends data to SPI device.

参数

device	the SPI device attached to SPI bus
send_buf	the buffer to be transmitted to SPI device.
length	the number of data to be transmitted.

返回

the actual length of send.

在文件 dev_spi.h 第 543 行定义.

{
    return rt_spi_transfer(device, send_buf, RT_NULL, length);
}

引用了 rt_spi_message::length, RT_NULL, rt_spi_transfer() , 以及 rt_spi_message::send_buf.

函数调用图:

rt_spi_message_append()

rt_inline void rt_spi_message_append	(	struct rt_spi_message *	list,
		struct rt_spi_message *	message )

This function appends a message to the SPI message list.

参数

list	the SPI message list header.
message	the message pointer to be appended to the message list.

在文件 dev_spi.h 第 556 行定义.

{
    RT_ASSERT(list != RT_NULL);
    if (message == RT_NULL)
        return; /* not append */
 
    while (list->next != RT_NULL)
    {
        list = list->next;
    }
 
    list->next = message;
    message->next = RT_NULL;
}

引用了 rt_spi_message::next, RT_ASSERT , 以及 RT_NULL.

rt_qspi_configure()

rt_err_t rt_qspi_configure	(	struct rt_qspi_device *	device,
		struct rt_qspi_configuration *	cfg )

This function can set configuration on QSPI device.

参数

device	the QSPI device attached to QSPI bus.
cfg	the configuration pointer.

返回

the actual length of transmitted.

rt_qspi_bus_register()

rt_err_t rt_qspi_bus_register	(	struct rt_spi_bus *	bus,
		const char *	name,
		const struct rt_spi_ops *	ops )

This function can register a SPI bus for QSPI mode.

参数

bus	the SPI bus for QSPI mode.
name	The name of the spi bus.
ops	the SPI bus instance to be registered.

返回

the actual length of transmitted.

rt_qspi_transfer_message()

rt_size_t rt_qspi_transfer_message	(	struct rt_qspi_device *	device,
		struct rt_qspi_message *	message )

This function transmits data to QSPI device.

参数

device	the QSPI device attached to QSPI bus.
message	the message pointer.

返回

the actual length of transmitted.

rt_qspi_send_then_recv()

rt_err_t rt_qspi_send_then_recv	(	struct rt_qspi_device *	device,
		const void *	send_buf,
		rt_size_t	send_length,
		void *	recv_buf,
		rt_size_t	recv_length )

This function can send data then receive data from QSPI device

参数

device	the QSPI device attached to QSPI bus.
send_buf	the buffer to be transmitted to QSPI device.
send_length	the number of data to be transmitted.
recv_buf	the buffer to be recivied from QSPI device.
recv_length	the data to be recivied.

返回

the status of transmit.

rt_qspi_send()

rt_err_t rt_qspi_send	(	struct rt_qspi_device *	device,
		const void *	send_buf,
		rt_size_t	length )

This function can send data to QSPI device

参数

device	the QSPI device attached to QSPI bus.
send_buf	the buffer to be transmitted to QSPI device.
length	the number of data to be transmitted.

返回

the status of transmit.