Collaboration diagram for SPI:

Data Structures
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

Macros
#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_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)

Functions
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)

Detailed Description

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);

Macro Definition Documentation

◆ 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

◆ RT_SPI_CPOL

#define RT_SPI_CPOL (1<<1)

bit[1]:CPOL, clock polarity

◆ RT_SPI_LSB

#define RT_SPI_LSB (0<<2)

bit[2]: 0-LSB

◆ RT_SPI_MSB

#define RT_SPI_MSB (1<<2)

bit[2]: 1-MSB

◆ RT_SPI_MASTER

#define RT_SPI_MASTER (0<<3)

SPI master device

◆ RT_SPI_SLAVE

#define RT_SPI_SLAVE (1<<3)

SPI slave device

◆ RT_SPI_CS_HIGH

#define RT_SPI_CS_HIGH (1<<4)

Chipselect active high

◆ RT_SPI_NO_CS

#define RT_SPI_NO_CS (1<<5)

No chipselect

◆ RT_SPI_3WIRE

#define RT_SPI_3WIRE (1<<6)

SI/SO pin shared

◆ RT_SPI_READY

#define RT_SPI_READY (1<<7)

Slave pulls low to pause

◆ RT_SPI_MODE_0

#define RT_SPI_MODE_0 (0 | 0)

CPOL = 0, CPHA = 0

◆ RT_SPI_MODE_1

#define RT_SPI_MODE_1 (0 | RT_SPI_CPHA)

CPOL = 0, CPHA = 1

◆ RT_SPI_MODE_2

#define RT_SPI_MODE_2 (RT_SPI_CPOL | 0)

CPOL = 1, CPHA = 0

◆ RT_SPI_MODE_3

#define RT_SPI_MODE_3 (RT_SPI_CPOL | RT_SPI_CPHA)

CPOL = 1, CPHA = 1

Function Documentation

◆ 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

Parameters

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

Returns: 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

Parameters

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

Returns: 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

Parameters

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

Returns: 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.

Parameters

device Pointer to the SPI device attached to the SPI bus.

Return values

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.

Note: 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.

Parameters

device the SPI device attached to SPI bus

Returns: 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.

Parameters

device the SPI device attached to SPI bus

Returns: 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).

Parameters

device the SPI device attached to SPI bus

Returns: 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).

Parameters

device the SPI device attached to SPI bus

Returns: 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.

Parameters

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

Return values

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.

Parameters

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.

Returns: 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.

Parameters

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.

Returns: 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.

Parameters

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.

Returns: 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.

Parameters

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

Returns: 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.

Parameters

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

Returns: 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.

Parameters

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

Returns: 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.

Parameters

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

Returns: the actual length of received.

◆ 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.

Parameters

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.

Returns: the actual length of send.

◆ 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.

Parameters

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

◆ 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.

Parameters

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

Returns: 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.

Parameters

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

Returns: 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.

Parameters

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

Returns: 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.

Parameters

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.

Returns: 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.

Parameters

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.

Returns: the status of transmit.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ RT_SPI_CPHA

◆ RT_SPI_CPOL

◆ RT_SPI_LSB

◆ RT_SPI_MSB

◆ RT_SPI_MASTER

◆ RT_SPI_SLAVE

◆ RT_SPI_CS_HIGH

◆ RT_SPI_NO_CS

◆ RT_SPI_3WIRE

◆ RT_SPI_READY

◆ RT_SPI_MODE_0

◆ RT_SPI_MODE_1

◆ RT_SPI_MODE_2

◆ RT_SPI_MODE_3

Function Documentation

◆ rt_spi_bus_register()

◆ rt_spi_bus_attach_device()

◆ rt_spi_bus_attach_device_cspin()

◆ rt_spi_bus_configure()

◆ rt_spi_take_bus()

◆ rt_spi_release_bus()

◆ rt_spi_take()

◆ rt_spi_release()

◆ rt_spi_configure()

◆ rt_spi_send_then_recv()

◆ rt_spi_send_then_send()

◆ rt_spi_transfer()

◆ rt_spi_sendrecv8()

◆ rt_spi_sendrecv16()

◆ rt_spi_transfer_message()

◆ rt_spi_recv()

◆ rt_spi_send()

◆ rt_spi_message_append()

◆ rt_qspi_configure()

◆ rt_qspi_bus_register()

◆ rt_qspi_transfer_message()

◆ rt_qspi_send_then_recv()

◆ rt_qspi_send()